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NAME 

intro - introduction to system calls and error numbers 

SYNOPSIS 

#include <errno.h> 

DESCRIPTION 

This section describes all of the system calls. Most of these calls have one or more error returns. An error 
condition is indicated by an otherwise impossible return value. This is almost always -1; the individual 
descriptions specify the details. 

As with normal arguments, all return codes and values from functions are of type integer unless otherwise 
noted. An error number is also made available in the external variable errno, which is not cleared on suc- 
cessful calls. Thus errno should be tested only after an error has occurred. 

The following is a complete list of the errors and their names as given in <errno.h>. 

0 Error 0 
Unused. 

1 EPERM Not owner 

Typically this error indicates an attempt to modify a file in some way forbidden except to its 
owner or super-user. It is also returned for attempts by ordinary users to do things allowed only to 
the super-user. 

2 ENOENT No such file or directory 

This error occurs when a file name is specified and the file should exist but doesn’t, or when one 
of the directories in a path name does not exist. 

3 ESRCH No such process 

The process whose number was given to kill and ptrace does not exist, or is already dead. 

4 EINTR Interrupted system call 

An asynchronous signal (such as interrupt or quit), which the user has elected to catch, occurred 
during a system call. If execution is resumed after processing the signal, it will appear as if the 
interrupted system call returned this error condition. 

5 EIO I/O error 

Some physical I/O error occurred during a read or write. This error may in some cases occur on a 
call following the one to which it actually applies. 

6 ENXIO No such device or address 

I/O on a special file refers to a subdevice which does not exist, or beyond the limits of the device. 
It may also occur when, for example, an illegal tape drive unit number is selected or a disk pack is 
not loaded on a drive. 

7 E2BIG Arg list too long 

An argument list longer than 10240 bytes is presented to execve . 

8 ENOEXEC Exec format error 

A request is made to execute a file which, although it has the appropriate permissions, does not 
start with a valid magic number, see a.out( 5). 

9 EBADF Bad file number 

Either a file descriptor refers to no open file, or a read (resp. write) request is made to a file which 
is open only for writing (resp. reading). 

10 ECHILD No children 

Wait and the process has no living or unwaited-for children. 

11 EAGAIN No more processes 

In a fork, the system’s process table is full or the user is not allowed to create any more processes. 
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12 ENOMEM Not enough core 

During an execve or break, a program asks for more address space or swap space than the system 
is able to supply. A lack of swap space is normally a temporary condition, however a lack of 
address space is not a temporary condition; the maximum size of the text, data, and stack seg- 
ments is a system parameter. 

13 EACCES Permission denied 

An attempt was made to access a file in a way forbidden by the protection system. 

14 EFAULT Bad address 

The system encountered a hardware fault in attempting to access the arguments of a system call. 

15 ENOTBLK Block device required 

A plain file was mentioned where a block device was required, for example, in mount. 

16 EBUSY Mount device busy 

An attempt to mount a device that was already mounted or an attempt was made to dismount a 
device on which there is an active file directory, (open file, current directory, mounted-on file, 
active text segment). 

17 EEXIST File exists 

An existing file was mentioned in an inappropriate context, for example, link. 

18 EXDEV Cross-device link 

A hard link to a file on another device was attempted. 

19 ENODEV No such device 

An attempt was made to apply an inappropriate system call to a device; for example, read a 
write-only device. 

20 ENOTDIR Not a directory 

A non-directory was specified where a directory is required, for example in a path name or as an 
argument to chdir. 

21 EISDIR Is a directory 

An attempt to write on a directory. 

22 EINVAL Invalid argument 

Some invalid argument: dismounting a non-mounted device, mentioning an unknown signal in 
signal, reading or writing a file for which seek has generated a negative pointer. Also set by math 
functions, see intro (3). 

23 ENFILE File table overflow 

The system’s table of open files is full, and temporarily no more opens can be accepted. 

24 EMFILE Too many open files 

Customary configuration limit is 20 per process. 

25 ENOTTY Not a typewriter 

The file mentioned in an ioctl is not a terminal or one of the other devices to which these calls 
apply. 

26 ETXTBSY Text file busy 

An attempt to execute a pure-procedure program which is currently open for writing (or reading!). 
Also an attempt to open for writing a pure-procedure program that is being executed. 

27 EFBIG File too large 

The size of a file exceeded the maximum (about 10 9 bytes). 

28 ENOSPC No space left on device 

A write to an ordinary file, the creation of a directory or symbolic link, or the creation of a direc- 
tory entry failed because no more disk blocks are available on the file system, or the allocation of 
an inode for a newly created file failed because no more inodes are available on the file system. 
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29 ESPIPE Illegal seek 

An Iseek was issued to a pipe. This error may also be issued for other non-seekable devices. 

30 EROFS Read-only file system 

An attempt to modify a file or directory was made on a device mounted read-only. 

31 EMLINK Too many links 

An attempt to make more than 32767 hard links to a file. 

32 EPIPE Broken pipe 

A write on a pipe or socket for which there is no process to read the data. This condition normally 
generates a signal; the error is returned if the signal is ignored. 

33 EDOM Math argument 

The argument of a function in the math library (as described in section 3M) is out of the domain of 
the function. 

34 ERANGE Result too large 

The value of a function in the math library (as described in section 3M) is unrepresentable within 
machine precision. 

35 EWOULDBLOCK Operation would block 

An operation which would cause a process to block was attempted on a object in non-blocking 
mode (see ioctl( 2)). 

36 EDSTPROGRESS Operation now in progress 

An operation which takes a long time to complete (such as a connect ( 2)) was attempted on a non- 
blocking object (see ioctl(2 )). 

37 EALREADY Operation already in progress 

An operation was attempted on a non-blocking object which already had an operation in progress. 

38 ENOTSOCK Socket operation on non-socket 

Self-explanatory. 

39 EDESTADDRREQ Destination address required 

A required address was omitted from an operation on a socket. 

40 EMSGSIZE Message too long 

A message sent on a socket was larger than the internal message buffer. 

41 EPROTOTYPE Protocol wrong type for socket 

A protocol was specified which does not support the semantics of the socket type requested. For 
example you cannot use the ARPA Internet UDP protocol with type SOCK STREAM. 

42 ENOPROTOOPT Bad protocol option 

A bad option was specified in a getsockopt( 2) or setsockopt(2) call. 

43 EPROTONOSUPPORT Protocol not supported 

The protocol has not been configured into the system or no implementation for it exists. 

44 ESOCKTNOSUPPORT Socket type not supported 

The support for the socket type has not been configured into the system or no implementation for 
it exists. 

45 EOPNOTSUPP Operation not supported on socket 

For example, trying to accept a connection on a datagram socket. 

46 EPFNOSUPPORT Protocol family not supported 

The protocol family has not been configured into the system or no implementation for it exists. 

47 EAFNOSUPPORT Address family not supported by protocol family 

An address incompatible with the requested protocol was used. For example, you shouldn’t 
necessarily expect to be able to use PUP Internet addresses with ARPA Internet protocols. 
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48 EADDRINUSE Address already in use 

Only one usage of each address is normally permitted. 

49 EADDRNOTAVAIL Can’t assign requested address 

Normally results from an attempt to create a socket with an address not on this machine. 

50 ENETDOWN Network is down 

A socket operation encountered a dead network. 

51 ENETUNREACH Network is unreachable 

A socket operation was attempted to an unreachable network. 

52 ENETRESET Network dropped connection on reset 

The host you were connected to crashed and rebooted. 

53 ECONNABORTED Software caused connection abort 

A connection abort was caused internal to your host machine. 

54 ECONNRESET Connection reset by peer 

A connection was forcibly closed by a peer. This normally results from the peer executing a shut- 
down (2) call. 

55 ENOBUFS No buffer space available 

An operation on a socket or pipe was not performed because the system lacked sufficient buffer 
space. 

56 EISCONN Socket is already connected 

A connect request was made on an already connected socket; or, a sendto or sendmsg request on a 
connected socket specified a destination other than the connected party. 

57 ENOTCONN Socket is not connected 

An request to send or receive data was disallowed because the socket is not connected. 

58 ESHUTDOWN Can’t send after socket shutdown 

A request to send data was disallowed because the socket had already been shut down with a pre- 
vious shutdown (2) call. 

59 unused 

60 ETIMEDOUT Connection timed out 

A connect request failed because the connected party did not properly respond after a period of 
time. (The timeout period is dependent on the communication protocol.) 

61 ECONNREFUSED Connection refused 

No connection could be made because the target machine actively refused it This usually results 
from trying to connect to a service which is inactive on the foreign host. 

62 ELOOP Too many levels of symbolic links 

A path name lookup involved more than 8 symbolic links. 

63 ENAMETOOLONG File name too long 

A component of a path name exceeded 255 characters, or an entire path name exceeded 1023 
characters. 

64 EHOSTDOWN Host is down 

A socket operation encountered a dead host. 

65 EHOSTUNREACH No route to host 

A socket operation was attempted to an unreachable host. 

66 ENOTEMPTY Directory not empty 

A directory with entries other than and was supplied to a remove directory or rename 
call. 
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67 mused 

68 mused 

69 EDQUOT Disc quota exceeded 

A write to an ordinary file, the creation of a directory or symbolic link, or the creation of a direc- 
tory entry failed because the user’s quota of disk blocks was exhausted, or the allocation of an 
inode for a newly created file failed because the user’s quota of inodes was exhausted. 

70 ESTALE Stale NFS file handle 

A client referenced a an open file, when the file has been deleted. 

71 EREMOTE Too many levels of remote in path 

An attempt was made to remotely mount a file system into a path which already has a remotely 
mounted component. 

DEFINITIONS 

Descriptor 

An integer assigned by the system when a file is referenced by open( 2), dup( 2), or pipe(2) or a 
socket is referenced by socket (2) or socketpair( 2) which uniquely identifies an access path to that file 
or socket from a given process or any of its children. 

Directory 

A directory is a special type of file which contains entries which are references to other files. Direc- 
tory entries are called links. By convention, a directory contains at least two links, . and .., referred 
to as dot and dot-dot respectively. Dot refers to the directory itself and dot-dot refers to its parent 
directory. 

Effective User Id, Effective Group Id, and Access Groups 

Access to system resources is governed by three values: the effective user ID, the effective group ID, 
and the group access list. 

The effective user ID and effective group ID are initially the process’s real user ID and real group ID 
respectively. Either may be modified through execution of a set-user-DD or set-group-ID file (possi- 
bly by one its ancestors); see execve (2). 

The group access list is an additional set of group ID’s used only in determining resource accessibil- 
ity. Access checks are performed as described below in “File Access Permissions”. 

File Access Permissions 

Every file in the file system has a set of access permissions. These permissions are used in determin- 
ing whether a process may perform a requested operation on the file (such as opening a file for writ- 
ing). Access permissions are established at the time a file is created. They may be changed at some 
later time through the chmod(2) call. 

File access is broken down according to whether a file may be: read, written, or executed. Directory 
files use the execute permission to control if the directory may be searched. 

File access permissions are interpreted by the system as they apply to three different classes of users: 
the owner of the file, those users in the file’s group, anyone else. Every file has an independent set of 
access permissions for each of these classes. When an access check is made, the system decides if 
permission should be granted by checking the access information applicable to the caller. 

Read, write, and execute/search permissions on a file are granted to a process if: 

The process’s effective user ID is that of the super-user. 

The process’s effective user ID matches the user ID of the owner of the file and the owner permis- 
sions allow the access. 

The process’s effective user ID does not match the user ID of the owner of the file, and either the 
process’s effective group ID matches the group ID of the file, or the group ID of the file is in the 
process’s group access list, and the group permissions allow the access. 
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Neither the effective user ID nor effective group ID and group access list of the process match the 
corresponding user ID and group ID of the file, but the permissions for “other users” allow access. 

Otherwise, permission is denied. 

File Name 

Names consisting of up to 255 characters may be used to name an ordinary file, special file, or direc- 
tory. 

These characters may be selected from the set of all ASCII character excluding 0 (null) and the 
ASCII code for / (slash). (The parity bit, bit 8, must be 0.) 

Note that it is generally unwise to use *, ?, [ or ] as part of file names because of the special meaning 
attached to these characters by the shell. 

Parent Process ID 

A new process is created by a currently active process; see fork(2). The parent process ID of a pro- 
cess is the process ID of its creator. 

Path Name 

A path name is a null-terminated character string starting with an optional slash (/), followed by zero 
or more directory names separated by slashes, optionally followed by a file name. The total length of 
a path name must be less than {MAXPATHLEN} (1024) characters. 

If a path name begins with a slash, the path search begins at the root directory. Otherwise, the search 
begins from the current working directory. A slash by itself names the root directory. A null path- 
name refers to the current directory. 

Process Group ID 

Each active process is a member of a process group that is identified by a positive integer called the 
process group ID. This is the process ID of the group leader. This grouping permits the signalling of 
related processes (see killpg( 2)) and the job control mechanisms of csh(l). 

Process ID 

Each active process in the system is uniquely identified by a positive integer called a process ID. 
The range of this ID is from 0 to 30000. 

Real User ID and Real Group ID 

Each user on the system is identified by a positive integer termed the real user ID. 

Each user is also a member of one or more groups. One of these groups is distinguished from others 
and used in implementing accounting facilities. The positive integer corresponding to this dis- 
tinguished group is termed the real group ID. 

All processes have a real user ID and real group ID. These are initialized from the equivalent attri- 
butes of the process which created it. 

Root Directory and Current Working Directory 

Each process has associated with it a concept of a root directory and a current working directory for 
the purpose of resolving path name searches. A process’s root directory need not be the root direc- 
tory of the root file system. 

Sockets and Address Families 

A socket is an endpoint for communication between processes. Each socket has queues for sending 
and receiving data. 

Sockets are typed according to their communications properties. These properties include whether 
messages sent and received at a socket require the name of the partner, whether communication is 
reliable, the format used in naming message recipients, etc. 

Each instance of the system supports some collection of socket types; consult socket { 2) for more 
information about the types available and their properties. 

Each instance of the system supports some number of sets of communications protocols. Each 
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protocol set supports addresses of a certain format. An Address Family is the set of addresses for a 
specific group of protocols. Each socket has an address chosen from the address family in which the 
socket was created. 

Special Processes 

The processes with a process ID’s of 0, 1, and 2 are special. Process 0 is the scheduler. Process 1 is 
the initialization process init, and is the ancestor of every other process in the system. It is used to 
control the process structure. Process 2 is the paging daemon. 

Super-user 

A process is recognized as a super-user process and is granted special privileges if its effective user 
ID is 0. 

Tty Group ED 

Each active process can be a member of a terminal group that is identified by a positive integer 
called the tty group ID. This grouping is used to arbitrate between multiple jobs contending for the 
same terminal; see csh( 1), and tty(4). 

SEE ALSO 

intro(3), perror(3) 
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NAME 

accept - accept a connection on a socket 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

ns - accept(s, addr, addrlen) 
int ns, s; 

struct sockaddr *addr; 
int *addrlen; 

DESCRIPTION 

The argument j is a socket which has been created with socket {2), bound to an address with bind{ 2), and is 
listening for connections after a listen (2). Accept extracts the first connection on the queue of pending con- 
nections, creates a new socket with the same properties of s and allocates a new file descriptor, ns, for the 
socket. If no pending connections are present on the queue, and the socket is not marked as non-blocking, 
accept blocks the caller until a connection is present If the socket is marked non-blocking and no pending 
connections are present on the queue, accept returns an error as described below. The accepted socket, ns, 
is used to read and write data to and from the socket which connected to this one; it is not used to accept 
more connections. The original socket s remains open for accepting further connections. 

The argument addr is a result parameter which is filled in with the address of the connecting entity, as 
known to the communications layer. The exact format of the addr parameter is determined by the domain 
in which the communication is occurring. The addrlen is a value-result parameter; it should initially con- 
tain the amount of space pointed to by addr; on return it will contain the actual length (in bytes) of the 
address returned. This call is used with connection-based socket types, currently with SOCKSTREAM. 

It is possible to select (2) a socket for the purposes of doing an accept by selecting it for read. 

RETURN VALUE 

The call returns -1 on error. If it succeeds it returns a non-negative integer which is a descriptor for the 
accepted socket. 

ERRORS 

The accept will fail if: 

[EBADF] 

[ENOTSOCK] 

(EOPNOTSUPP] 

[EFAULT] 

[EWOULDBLOCK] 

SEE ALSO 

bind(2), connect(2), listen(2), select(2), socket(2) 


The descriptor is invalid. 

The descriptor references a file, not a socket. 

The referenced socket is not of type SOCK STREAM. 

The addr parameter is not in a writable part of the user address space. 

The socket is marked non-blocking and no connections are present to be accepted. 
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NAME 

access - determine accessibility of file 
SYNOPSIS 

#include <sys/file.h> 

#define R_OK 4 /* test for read permission *1 

#define W OK 2 /* test for write permission */ 

#define X_OK 1 I* test for execute (search) permission */ 

#define F_OK 0 /* test for presence of file *1 

accessible = access(path, mode) 
int accessible; 
char *path; 
int mode; 

DESCRIPTION 

Access checks the given file path for accessibility according to mode, which is an inclusive or of the bits 
R_OK, W OK and X_OK. Specifying mode as F_OK (that is, 0) tests whether the directories leading to 
the file can be searched and the file exists. 

The real user ID and the group access list (including the real group ID) are used in verifying permission, so 
this call is useful to set-UID programs. 

Notice that only access bits are checked. A directory may be indicated as writable by access, but an 
attempt to open it for writing will fail (although files may be created there); a file may look executable, but 
execve will fail unless it is in proper format. 

RETURN VALUE 

If path cannot be found or if any of the desired access modes would not be granted, then a -1 value is 
returned; otherwise a 0 value is returned. 

ERRORS 

Access to the file is denied if one or more of the following are true: 

[EIO] An I/O error occurred while reading from or writing to the file system. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENAMETOOLONG] 

The argument path name was too long. 

[ENOENT] The named file does not exist. 

[EPERM] The argument contains a byte with the high-order bit set. 

[ELOOP] Too many symbolic links were encountered in translating the pathname. 

[EROFS] Write access is requested for a file on a read-only file system. 

[ETXTBSY] Write access is requested for a pure procedure (shared text) file that is being executed. 

[EACCES] Permission bits of the file mode do not permit the requested access; or search permission 

is denied on a component of the path prefix. The owner of a file has permission checked 
with respect to the “owner” read, write, and execute mode bits, members of the file’s 
group other than the owner have permission checked with respect to the “group” mode 
bits, and all others have permissions checked with respect to the “other” mode bits. 

[EFAULT] Path points outside the process’s allocated address space. 

SEE ALSO 

chmod(2), stat(2) 
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NAME 

acct - turn accounting on or off 

SYNOPSIS 

acct(file) 
char *file; 


DESCRIPTION 

The system is prepared to write a record in an accounting file for each process as it terminates. This call, 
with a null-terminated string naming an existing file as argument, turns on accounting; records for each ter- 
minating process are appended to file . An argument of 0 causes accounting to be turned off. 

The accounting file format is given in acct (5). 

This call is permitted only to the super-user. 

NOTES 

Accounting is automatically disabled when the file system the accounting file resides on runs out of space; 
it is enabled when space once again becomes available. 


RETURN VALUE 

On error —1 is returned. The file must exist and the call may be exercised only by the super-user. It is 
erroneous to try to turn on accounting when accounting is already on. 

ERRORS 

Acct will fail if one of the following is true: 


[EIO] An I/O error occurred while reading from or writing to the file system. 

[ENAMETOOLONG] 


[EPERM] 

[EPERM] 

[ENOTDIR] 

[ENOENT] 

[EROFS] 

DEFAULT] 

[ELOOP] 

[EACCES] 


The argument path name was too long. 

The caller is not the super-user. 

The pathname contains a character with the high-order bit set 
A component of the path prefix is not a directory. 

The named file does not exist. 

The named file resides on a read-only file system. 

File points outside the process’s allocated address space. 

Too many symbolic links were encountered in translating the pathname. 
Either the file is not a plain file, or else search permission is denied. 


SEE ALSO 

acct(5), sa(8) 


BUGS 

No accounting is produced for programs running when a crash occurs. In particular nonterminating pro- 
grams are never accounted for. 


10 


Last change: 16 August 1985 


Sun Release 3.0 



ADJTIME ( 2 ) 


SYSTEM CALLS 


ADJTIME (2) 


NAME 

adjtime - ajdust time 
SYNOPSIS 

#include <sys/time.h> 

adjtime(tp, otp) 
struct timeval *tp, *otp; 

DESCRIPTION 

Adjtime adjusts the system’s notion of the current time. The time is adjusted by the amount of time in *tp. 
The old adjustment value is returned in *otp. 

The adjustment is effected by speeding up or slowing down the system’s clock by a fixed percentage, 
currently 10%. 

The structures pointed to by tp and otp are defined in <sysltime.h> as: 
struct timeval { 

u long tv sec; /* seconds since Jan. 1, 1970 */ 

long tv_usec; /* and microseconds */ 

}; 

If otp is a zero pointer, the corresponding information will not be returned. 

Only the super-user may adjust the time of day. 

The adjustment value will be silently rounded to the resolution of the system clock. 

RETURN 

A 0 return value indicates that the call succeeded. A -1 return value indicates an error occurred, and in this 
case an error code is stored into the global variable err no. 

ERRORS 

The following error codes may be set in errno: 

[EFAULT] An argument address referenced invalid memory. 

[EPERM] A user other than the super-user attempted to set the time. 

SEE ALSO 

settimeofday(2), date(l) 
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NAME 

bind - bind a name to a socket 


SYNOPSIS 

^include <sys/types.h> 

#include <sys/socket.h> 

bind(s, name, namelen) 
int s; 

struct sockaddr *name; 
int namelen; 

DESCRIPTION 

Bind assigns a name to an unnamed socket. When a socket is created with socket^ 2) it exists in a name 
space (address family) but has no name assigned. Bind requests the name, be assigned to the socket. 

NOTES 

Binding a name in the UNIX domain creates a socket in the file system which must be deleted by the caller 
when it is no longer needed (using unlink(2)). 

The rules used in name binding vary between communication domains. Consult the manual entries in sec- 
tion 4 for detailed information. 

RETURN VALUE 

If the bind is successful, a 0 value is returned. A return value of -1 indicates an error, which is further 
specified in the global err no. 

ERRORS 

The bind call will fail if: 


[EBADF] 

[ENOTSOCK] 

[E ADDRN OTAV AIL] 

[EADDRINUSE] 

[EINVAL] 

[EACCES] 


S is not a valid descriptor. 

S is not a socket 

The specified address is not available from the local machine. 

The specified address is already in use. 

The socket is already bound to an address. 

The requested address is protected, and the current user has inadequate permission 
to access it 


[EF AULT] The name parameter is not in a valid part of the user address space. 

SEE ALSO 

connect(2), listen(2), socket(2), getsockname(2) 

BUGS 

The file created is a side-effect of the current implementation and will not be created in future versions of 
the UNIX ipc domain. 
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NAME 

brk, sbrk - change data segment size 

SYNOPSIS 

caddr_t brk(addr) 
caddr_t addr; 

caddr_t sbrk(incr) 
int incr; 

DESCRIPTION 

Brk sets the system’s idea of the lowest data segment location not used by the program (called the break) to 
addr (rounded up to the next multiple of the system’s page size). Locations greater than addr and below 
the stack pointer are not in the address space and will thus cause a memory violation if accessed. 

In the alternate function sbrk , incr more bytes are added to the program’s data space and a pointer to the 
start of the new area is returned. 

When a program begins execution via execve the break is set at the highest location defined by the program 
and data storage areas. Ordinarily, therefore, only programs with growing data areas need to use sbrk. 

The getrlimit( 2) system call may be used to determine the maximum permissible size of the data segment; 
it will not be possible to set the break beyond the rlim max value returned from a call to getrlimit, e.g. 
“etext + rip— »rlim_max.” (See end( 3) for the definition of etext.) 

RETURN VALUE 

Zero is returned if the brk could be set; -1 if the program requests more memory than the system limit 
Sbrk normally returns the current value of the break, but -1 if it could not be set. 

ERRORS 

Sbrk will fail and no additional memory will be allocated if one of the following are true: 

[ENOMEM] The limit as set by setrlimit( 2), was exceeded. 

[ENOMEM] The maximum possible size of a data segment (compiled into the system) was exceeded. 
[ENOMEM] Insufficient space existed in the swap area to support the expansion. 

SEE ALSO 

execve(2), getrlimit(2), malloc(3), end(3) 

BUGS 

Setting the break may fail due to a temporary lack of swap space. It is not possible to distinguish this from 
a failure caused by exceeding the maximum size of the data segment without consulting getrlimit. 
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NAME 

chdir - change current working directory 

SYNOPSIS 

chdir(path) 
char *path; 

DESCRIPTION 

Path is the pathname of a directory. Chdir causes this directory to become the current working directory, 
the starting point for path names not beginning with 

In order for a directory to become the current directory, a process must have execute (search) access to the 
directory. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of —1 is returned and errno is set 
to indicate the error. 

ERRORS 

Chdir will fail and the current working directory will be unchanged if one or more of the following are 
true: 

[EIO] An I/O error occurred while reading from or writing to the file system. 

[ENOTDER] A component of the pathname is not a directory. 

[ENOENT] The named directory does not exist. 

[ENAMETOOLONG] 

The argument path name was too long. 

[EPERM] The argument contains a byte with the high-order bit set. 

[EACCES] Search permission is denied for any component of the path name. 

[EFAULT] Path points outside the process’s allocated address space. 

[ELOOP] Too many symbolic links were encountered in translating the pathname. 

SEE ALSO 

chroot(2) 
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NAME 

chmod, fchmod - change mode of file 

SYNOPSIS 

chmod(path, mode) 
char *path; 
int mode; 

fchmod(fd, mode) 
int fd, mode; 

DESCRIPTION 

The file whose name is given by path or referenced by the descriptor fd has its mode changed to mode. 
Modes are constructed by or’ing together some combination of the following: 

04000 set user ID on execution 
02000 set group ID on execution 
01000 save text image after execution 
00400 read by owner 
00200 write by owner 

00100 execute (search on directory) by owner 
00070 read, write, execute (search) by group 
00007 read, write, execute (search) by others 

If an executable file is set up for sharing (this is the default) then mode 1000 prevents the system from 
abandoning the swap-space image of the program-text portion of the file when its last user terminates. 
Ability to set this bit is restricted to the super-user. 

Only the owner of a file (or the super-user) may change the mode. 

Writing or changing the owner of a file turns off the set-user-id and set-group-id bits. This makes the sys- 
tem somewhat more secure by protecting set-user-id (set-group-id) files from remaining set-user-id (set- 
group-id) if they are modified, at the expense of a degree of compatibility. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set 
to indicate the error. 

ERRORS 

Chmod will fail and the file mode will be unchanged if: 

[EIO] An I/O error occurred while reading from or writing to the file system. 

[EPERM] The argument contains a byte with the high-order bit set. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENAMETOOLONG] 

The pathname was too long. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied on a component of the path prefix. 

[EPERM] The effective user ID does not match the owner of the file and the effective user ID is 

not the super-user. 

[EROFS] The named file resides on a read-only file system. 

DEFAULT] Path points outside the process’s allocated address space. 

[ELOOP] Too many symbolic links were encountered in translating the pathname. 

Fchmod will fail if: 

[EPERM] The effective user ID does not match the owner of the file and the effective user ID is 
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not the super-user. 

[EBADF] The descriptor is not valid. 

[EINVAL] Fd refers to a socket, not to a file. 

[EROFS] The file resides on a read-only file system. 

SEE ALSO 

open(2), chown(2) 
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NAME 

chown, fchown - change owner and group of a file 
SYNOPSIS 

chown(path, owner, group) 

char *path; 

int owner, group; 

fchown(fd, owner, group) 
int fd, owner, group; 

DESCRIPTION 

The file which is named by path or referenced by fd has its owner and group changed as specified. Only 
the super-user may execute this call, because if users were able to give files away, they could defeat the 
file-space accounting procedures. 

Chown clears the set-user-id and set-group-id bits on the file to prevent accidental creation of set-user-id 
and set-group-id programs owned by the super-user. 

Fchown is particularly useful when used in conjunction with the file locking primitives (see flock( 2)). 

Only one of the owner and group id’s may be set by specifying the other as -1. 

RETURN VALUE 

Zero is returned if the operation was successful; -1 is returned if an error occurs, with a more specific error 
code being placed in the global variable errno. 

ERRORS 

Chown will fail and the file will be unchanged if: 

[EIO] An I/O error occurred while reading from or writing to the file system. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENAMETOOLONG] 

The argument pathname is too long. 

[EPERM] The argument contains a byte with the high-order bit set. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied on a component of the path prefix. 

[EPERM] The effective user ID is not the super-user. 

[EROFS] The named file resides on a read-only file system. 

[EFAULT] Path points outside the process’s allocated address space. 

[ELOOP] Too many symbolic links were encountered in translating the pathname. 

Fchown will fail if: 

[EIO] An I/O error occurred while reading from or writing to the file system. 

[EBADF] Fd does not refer to a valid descriptor. 

[EINVAL] Fd refers to a socket, not a file. 

[EPERM] The effective user ID is not the super-user. 

[EROFS] The named file resides on a read-only file system. 

SEE ALSO 

chmod(2), flock(2) 
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NAME 

chroot - change root directory 

SYNOPSIS 

chroot(dirname) 
char *dirname; 

DESCRIPTION 

Dirname is the address of the pathname of a directory, terminated by a null byte. Chroot makes this direc- 
tory become the root directory, the starting point for path names beginning with This root directory 
setting is inherited across execve (2) and by all children of this process created with/ork(2) calls. 

In order for a directory to become the root directory a process must have execute (search) access to the 
directory. 

This call is restricted to the super-user. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of-1 is returned and errno is set 
to indicate an error. 

ERRORS 

Chroot will fail and the root directory will be unchanged if one or more of the following are true: 

[EIO] An I/O error occurred while reading from or writing to the file system. 

[ENOTDIR] A component of the path name is not a directory. 

[ENAMETOOLONG] 

The pathname was too long. 

[EPERM] The argument contains a byte with the high-order bit set. 

[ENOENT] The named directory does not exist. 

[EACCES] Search permission is denied for any component of the path name. 

[EFAULT] Path points outside the process’s allocated address space. 

[ELOOP] Too many symbolic links were encountered in translating the pathname. 

SEE ALSO 

chdir(2) 
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NAME 

close - delete a descriptor 

SYNOPSIS 

close(d) 

intd; 

DESCRIPTION 

The close call deletes a descriptor from the per-process object reference table. If this is the last reference 
to the underlying object, then it will be deactivated. For example, on the last close of a file the current seek 
pointer associated with the file is lost; on the last close of a socket (2) associated naming information and 
queued data are discarded; on the last close of a file holding an advisory lock the lock is released, see 
flock (2) for further information. 

A close of all of a process’s descriptors is automatic on exit, but since there is a limit on the number of 
active descriptors per process, close is necessary for programs which deal with many descriptors. 

When a process forks (see fork{ 2)), all descriptors for the new child process reference the same objects as 
they did in the parent before the fork. If a new process is then to be run using execve (2), the process would 
normally inherit these descriptors. Most of the descriptors can be rearranged with dup2 (2) or deleted with 
close before the execve is attempted, but if some of these descriptors will still be needed if the execve fails, 
it is necessary to arrange for them to be closed if the execve succeeds. For this reason, the call “fcntl(d, 
FSETFD, 1)” is provided which arranges that a descriptor will be closed after a successful execve; the 
call “fcnd(d, F SETFD, 0)” restores the default, which is to not close the descriptor. 

Close unmaps pages mapped through this file descriptor. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the global 
integer variable errno is set to indicate the error. 

ERRORS 

Close will fail if: 

[EBADF] D is not an active descriptor. 

SEE ALSO 

accept(2), flock(2), open(2), pipe(2), socket(2), socketpair(2), execve(2), fcntl(2), mmap(2), munmap(2) 
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NAME 

connect - initiate a connection on a socket 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

connect(s, name, namelen) 
ints; 

struct sockaddr *name; 
int namelen; 

DESCRIPTION 

The parameter s is a socket. If it is of type SOCKDGRAM, then this call permanently specifies the peer 
to which datagrams are to be sent; if it is of type SOCKSTREAM, then this call attempts to make a con- 
nection to another socket. The other socket is specified by name which is an address in the communica- 
tions space of the socket. Each communications space interprets the name parameter in its own way. 
RETURN VALUE 

If the connection or binding succeeds, then 0 is returned. Otherwise a -1 is returned, and a more specific 
error code is stored in err no. 

ERRORS 

The call fails if: 


[EBADF] 

[ENOTSOCK] 

[EADDRNOT AVAIL] 

[EAFNOSUPPORT] 

[EISCONN] 

[ETIMEDOUT] 

[ECONNREFUSED] 

[ENETUNREACH] 

[EADDRINUSE] 

[EFAULT] 

[EWOULDBLOCK] 


S is not a valid descriptor. 

5 is a descriptor for a file, not a socket 

The specified address is not available on this machine. 

Addresses in the specified address family cannot be used with this socket. 

The socket is already connected. 

Connection establishment timed out without establishing a connection. 

The attempt to connect was forcefully rejected. 

The network isn’t reachable from this host. 

The address is already in use. 

The name parameter specifies an area outside the process address space. 

The socket is non-blocking and the and the connection cannot be completed 
immediately. It is possible to select ( 2) the socket while it is connecting by select- 
ing it for writing. 


SEE ALSO 

accept(2), select(2), socket(2), getsockname(2) 
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NAME 

creat - create a new file 

SYNOPSIS 

creat(name, mode) 
char *name; 

DESCRIPTION 

This interface is obsoleted by open(2). 

Creat creates a new file or prepares to rewrite an existing file called name, given as the address of a null- 
terminated string. If the file did not exist, it is given mode mode, as modified by the process’s mode mask 
(see umask(2)). Also see chmod{ 2) for the construction of the mode argument. 

If the file did exist, its mode and owner remain unchanged, but it is truncated to 0 length. 

The file is also opened for writing, and its file descriptor is returned. 

NOTES 

The mode given is arbitrary; it need not allow writing. This feature has been used in the past by programs 
to construct a simple exclusive locking mechanism. It is replaced by the O EXCL open mode, or flock Q) 
facility. 

RETURN VALUE 

The value -1 is returned if an error occurs. Otherwise, the call returns a non-negative descriptor which 
only permits writing. 

ERRORS 

Creat will fail and the file will not be created or truncated if one of the following occur. 

[EPERM] The argument contains a byte with the high-order bit set. 

[ENOTDIR] A component of the path prefix is not a directory. 

[EACCES] A needed directory does not have search permission. 

[EACCES] The file does not exist and the directory in which it is to be created is not writable. 
[EACCES] The file exists, but it is unwritable. 

[EISDIR] The file is a directory. 

[EMFILE] There are already too many files open. 

[EROFS] The named file resides, or would reside, on a read-only file system. 

[ENXIO] The file is a character special or block special file, and the associated device does not 

exist. 

[ETXTBSY] The file is a pure procedure (shared text) file that is being executed. 

[EFAULT] Name points outside the process’s allocated address space. 

[ FT OOP] Too many symbolic links were encountered in translating the pathname. 

[EOPNOTSUPP] The file was a socket (not currently implemented). 

[ENOENT] A required component of the pathname does not exist. 

[ENAMETOOLONG] 

The pathname was too long. 

[ENFILE] The system file table is full. 

[ENOSPC] The directory in which the entry for the new file is being placed cannot be extended 
because there is no space left on the file system containing the directory. 

[ENOSPC] There are no free inodes on the file system on which the file is being created. 

[EDQUOT] The directory in which the entry for the new file is being placed cannot be extended 
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because the user’s quota of disk blocks on the file system containing the directory has 
been exhausted. 

[EDQUOT] The user’s quota of inodes on the file system on which the file is being created has been 
exhausted. 


[EIO] 
SEE ALSO 


An I/O error occurred while reading from or writing to the file system. 


open(2), write(2), close(2), chmod(2), umask(2) 
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NAME 

dup, dup2 - duplicate a descriptor 

SYNOPSIS 

newd = dup(oldd) 
int newd, oldd; 

dup2(oldd, newd) 
int oldd, newd; 

DESCRIPTION 

Dup duplicates an existing object descriptor. The argument oldd is a small non-negative integer index in 
the per-process descriptor table. The value must be less than the size of the table, which is returned by 
getdtablesize( 2). The new descriptor newd returned by the call is the lowest numbered descriptor which is 
not currendy in use by the process. 

The object referenced by the descriptor does not distinguish between references using oldd and newd in 
any way. Thus if newd and oldd are duplicate references to an open file, re ad (2), write(2 ) and lseelc(2) 
calls all move a single pointer into the file. If a separate pointer into the file is desired, a different object 
reference to the file must be obtained by issuing an additional open( 2) call. 

In the second form of the call, the value of newd desired is specified. If this descriptor is already in use, the 
descriptor is first deallocated as if a close (2) call had been done first. 

RETURN VALUE 

The value -1 is returned if an error occurs in either call. The external variable err no indicates the cause of 
the error. 

ERRORS 

Dup and dup2 fail if: 

[EBADF] Oldd or newd is not a valid active descriptor 

[EMFILE] Too many descriptors are active. 

SEE ALSO 

accept(2), open(2), close(2), pipe(2), socket(2), socketpair(2), getdtablesize(2) 
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NAME 

execve - execute a file 
SYNOPSIS 

execve(name, argv, envp) 
char *name, *argv[], *envp[]; 

DESCRIPTION 

Execve transforms the calling process into a new process. The new process is constructed from an ordinary 
file called the new process file. This file is either an executable object file, or a file of data for an inter- 
preter. An executable object file consists of an identifying header, followed by pages of data representing 
the initial program (text) and initialized data pages. Additional pages may be specified by the header to be 
initialize with zero data. See a.out( 5). 

An interpreter file begins with a line of the form “#! interpreter [arg]”. When an interpreter file is 
execve ’d, the system execve ’s the specified interpreter. If the optional arg is specified, it becomes the first 
argument to the interpreter, and the name of the originally execve’ d file becomes the second argument; 
otherwise, the name of the originally execve ’d file becomes the first argument. The original argument are 
shifted over to become the subsequent arguments. The zeroth argument, normally the name of the 
execve ’d file, is left unchanged. 

There can be no return from a successful execve because the calling core image is lost. This is the mechan- 
ism whereby different process images become active. 

The argument argv is an array of character pointers to null-terminated character strings. These strings con- 
stitute the argument list to be made available to the new process. By convention, at least one argument 
must be present in this array, and the first element of this array should be the name of the executed program 
(i.e. the last component of name). 

The argument envp is also an array of character pointers to null-terminated strings. These strings pass 
information to the new process which are not directly arguments to the command, see environ ( 5). 

Descriptors open in the calling process remain open in the new process, except for those for which the 
close-on-exec flag is set; see close ( 2). Descriptors which remain open are unaffected by execve. 

Ignored signals remain ignored across an execve, but signals that are caught are reset to their default 
values. The signal stack is reset to be undefined; see sigvec (2) for more information. 

Each process has a real user ID and group ID and an effective user ID and group ID. The real ID identifies 
the person using the system; the effective ID determines his access privileges. Execve changes the effective 
user and group ID to the owner of the executed file if the file has the “set-user-ID” or “set-group-ID” 
modes. The real user ID is not affected. 

The new process also inherits the following attributes from the calling process: 


process ID 

see getpid(2 ) 

parent process ID 

see getppid(2 ) 

process group ID 

see getpgrp( 2) 

access groups 

see getgroups(2) 

working directory 

see chdir(2) 

root directory 

see chroot(2) 

control terminal 

see tty (4) 

resource usages 

see getrusage( 2) 

interval timers 

see getitimer( 2) 

resource limits 

see getrlimit(2) 

file mode mask 

see umask(2) 

signal mask 

see sigvec (2) 


When the executed program begins, it is called as follows: 
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main(argc, argv, envp) 
int argc; 

char **argv, **envp; 

where argc is the number of elements in argv (the “arg count”) and argv is the array of character pointers 
to the arguments themselves. 

Envp is a pointer to an array of strings that constitute the environment of the process. A pointer to this 
array is also stored in the global variable “environ”. Each string consists of a name, an and a null- 
terminated value. The array of pointers is terminated by a null pointer. The shell jA( 1) passes an environ- 
ment entry for each global shell variable defined when the program is called. See environ(5) for some con- 
ventionally used names. 

RETURN VALUE 

If execve returns to the calling process an error has occurred; the return value will be -1 and the global 
variable errno will contain an error code. 

ERRORS 

Execve will fail and return to the calling process if one or more of the following are true: 

[ENOENT] One or more components of the new process file’s path name do not exist. 

[ENOTDIR] A component of the new process file is not a directory. 

[EACCES] Search permission is denied for a directory listed in the new process file’s path prefix. 
[EACCES] The new process file is not an ordinary file. 

[EACCES] The new process file mode denies execute permission. 

[ENOEXEC] The new process file has the appropriate access permission, but has an invalid magic 
number in its header. 

[ETXTBSY] The new process file is a pure procedure (shared text) file that is currently open for writ- 
ing or reading by some process. 

[ENOMEM] The new process requires more virtual memory than is allowed by the imposed max- 
imum ( getrlimit(2 )). 

[E2BIG] The number of bytes in the new process’s argument list is larger than the system- 

imposed limit of {ARG MAX} bytes. The current value of ARGMAX is 10240. 

[EFAULT] The new process file is not as long as indicated by the size values in its header. 
[EFAULT] Name , argv , or envp point to an illegal address. 

[ENAMETOOLONG] 

The pathname was too long. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

SEE ALSO 

exit(2), fork(2), execl(3), environ(5) 
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NAME 

_exit - terminate a process 

SYNOPSIS 

_exit(status) 
int status; 

DESCRIPTION 

exit terminates a process with the following consequences: 

All of the descriptors open in the calling process are closed. 

If the parent process of the calling process is executing a wait or is interested in the SIGCHLD signal, then 
it is notified of the calling process’s termination and the low-order eight bits of status are made available to 
it; see wait(2). The low-order 8 bits of status are available to the parent process. 

The parent process ID of all of the calling process’s existing child processes are also set to 1. This means 
that the initialization process (see intro (2)) inherits each of these processes as well. 

Most C programs will call the library routine exit (3) which performs cleanup actions in the standard i/o 
library before calling exit . 

RETURN VALUE 

This call never returns. 

SEE ALSO 

fork(2), wait(2), exit(3) 
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NAME 

fcntl - file control 

SYNOPSIS 

#include <fcntl.h> 

res = fcntl(fd, cmd, arg) 
int res; 

int fd, cmd, arg; 

DESCRIPTION 

Fcntl provides for control over descriptors. The argument fd is a descriptor to be operated on by cmd as 
follows: 

FDUPFD Return a new descriptor as follows: 

Lowest numbered available descriptor greater than or equal to arg. 

Same object references as the original descriptor. 

New descriptor shares the same file pointer if the object was a file. 

Same access mode (read, write or read/write). 

Same file status flags (i.e., both file descriptors share the same file status flags). 

The close-on-exec flag associated with the new file descriptor is set to remain open 
across execve (2) system calls. 

FGETFD Get the close-on-exec flag associated with the file descriptor fd. If the low-order bit is 0, 
the file will remain open across exec, otherwise the file will be closed upon execution of 
exec. 

FSETFD Set the close-on-exec flag associated with fd to the low order bit of arg (0 or 1 as above). 

F GETFL Get descriptor status flags, see fcntl (5) for their definitions. 

FSETFL Set descriptor status flags, see fcntl( 5) for their definitions. 

FGETOWN Get the process ID or process group currently receiving SIGIO and SIGURG signals; 

process groups are returned as negative values. 

F SETOWN Set the process or process group to receive SIGIO and SIGURG signals; process groups 
are specified by supplying arg as negative, otherwise arg is interpreted as a process ID. 

The SIGIO facilities are enabled by setting the FASYNC flag with F SETFL. 

RETURN VALUE 

Upon successful completion, the value returned depends on cmd as follows: 

F DUPFD A new file descriptor. 

FGETFD Value of flag (only the low-order bit is defined). 

F_GETFL Value of flags. 

F GETOWN Value of file descriptor owner, 

other Value other than -1. 

Otherwise, a value of-1 is returned and errno is set to indicate the error. 

ERRORS 

Fcntl will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[EMFILE] Cmd is F DUPFD and the maximum allowed number of file descriptors are currently 

open. 

[EINVAL] Cmd is F_DUPFD and arg is negative or greater the maximum allowable number (see 
getdtablesize (2)). 
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SEE ALSO 

close(2), execve(2), getdtablesize(2), open(2), sigvec(2) 
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NAME 

flock - apply or remove an advisory lock on an open file 


SYNOPSIS 

#include <sys/file.li> 

#define LOCK SH 1 

#define LOCK EX 2 

#define LOCKNB 4 

#define LOCK UN 8 

flock(fd, operation) 
int fd, operation; 


/* shared lock *1 
I* exclusive lock */ 

/* don’t block when locking */ 
I* unlock *1 


DESCRIPTION 

Flock applies or removes an advisory lock on the file associated with the file descriptor fd. A lock is 
applied by specifying an operation parameter which is the inclusive or of LOCK SH or LOCKEX and, 
possibly, LOCK NB. To unlock an existing lock operation should be LOCK UN. 

Advisory locks allow cooperating processes to perform consistent operations on files, but do not guarantee 
consistency (i.e. processes may still access files without using advisory locks possibly resulting in incon- 
sistencies). 


The locking mechanism allows two types of locks: shared locks and exclusive locks. At any time multiple 
shared locks may be applied to a file, but at no time are multiple exclusive, or both shared and exclusive, 
locks allowed simultaneously on a file. 

A shared lock may be upgraded to an exclusive lock, and vice versa, simply by specifying the appropriate 
lock type; this results in the previous lock being released and the new lock applied (possibly after other 
processes have gained and released the lock). 

Requesting a lock on an object which is already locked normally causes the caller to blocked until the lock 
may be acquired. If LOCK NB is included in operation, then this will not happen; instead the call will fail 
and the error EWOULDBLOCK will be returned. 


NOTES 

Locks are on files, not file descriptors. That is, file descriptors duplicated through dup(2) or fork{ 2) do not 
result in multiple instances of a lock, but rather multiple references to a single lock. If a process holding a 
lock on a file forks and the child explicitly unlocks the file, the parent will lose its lock. 

Processes blocked awaiting a lock may be awakened by signals. 

RETURN VALUE 

Zero is returned if the operation was successful; on an error a -1 is returned and an error code is left in the 
global location errno. 

ERRORS 

The flock call fails if: 

[EWOULDBLOCK] The file is locked and the LOCK NB option was specified. 

[EBADF] The argument fd is an invalid descriptor. 

[EINVAL] The argument fd refers to an object other than a file. 

SEE ALSO 

open(2), close(2), dup(2), execve(2), fork(2) 
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NAME 

fork - create a new process 
SYNOPSIS 

pid = forkO 
int pid; 

DESCRIPTION 

Fork creates a new process. The new process (child process) is an exact copy of the calling process except 
for the following: 

The child process has a unique process ID. 

The child process has a different parent process ID (that is, the process ID of the parent process). 

The child process has its own copy of the parent’s descriptors. These descriptors reference the 
same underlying objects, so that, for instance, file pointers in file objects are shared between the 
child and the parent, so that a lseek( 2) on a descriptor in the child process can affect a subsequent 
read or write by the parent. This descriptor copying is also used by the shell to establish standard 
input and output for newly created processes as well as to set up pipes. 

The child processes resource utilizations are set to 0; see setrlimit(2). 

RETURN VALUE 

Upon successful completion, fork returns a value of 0 to the child process and returns the process ID of the 
child process to the parent process. Otherwise, a value of -1 is returned to the parent process, no child pro- 
cess is created, and the global variable errno is set to indicate the error. 

ERRORS 

Fork will fail and no child process will be created if one or more of the following are true: 

[EAGAIN] The system-imposed limit {PROCMAX} on the total number of processes under exe- 
cution would be exceeded. The size of PROC MAX is determined when the system is 
generated. 

[EAGAIN] The system-imposed limit {KIDMAX} on the total number of processes under execu- 
tion by a single user would be exceeded. The size of KID MAX is determined when the 
system is generated. 

[ENOMEM] There is insufficient swap space for the new process. 

SEE ALSO 

execve(2), wait(2) 
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NAME 

fsync - synchronize a file’s in-core state with that on disk 

SYNOPSIS 

fsync(fd) 
int fd; 

DESCRIPTION 

Fsync moves all modified data and attributes of fd to a permanent storage device: all in-core modified 
copies of buffers for the associated file have been written to a disk when the call returns. Note that this is 
different than sync (2) which schedules disk I/O for all files (as though an fsync had been done on all files) 
but returns before the I/O completes. 

Fsync should be used by programs which require a file to be in a known state; for example in building a 
simple transaction facility. 

RETURN VALUE 

A 0 value is returned on success. A -1 value indicates an error. 

ERRORS 

The fsync fails if: 

[EBADF] 

[EINVAL] 

[EIO] 

SEE ALSO 

sync(2), sync(8), 

BUGS 

The current implementation of this call is expensive for large files. 


Fd is not a valid descriptor. 

Fd refers to a socket, not to a file. 

An I/O error occurred while reading from or writing to the file system. 
cron(8) 
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NAME 

getdirentries - gets directory entries in a filesystem independent format 

SYNOPSIS 

#include <sys/dir.h> 

cc = getdirentries(fd, buf, nbytes, basep) 

int cc, fd; 

char *buf; 

int nbytes; 

long *basep 

DESCRIPTION 

Getdirentries attempts to put directory entries from the directory referenced by the file descriptor fd into the 
buffer pointed to by buf, in a filesystem independent format. Up to nbytes of data will be transferred. 
Nbytes must be greater than or equal to the block size associated with the file, see stat(2). Sizes less than 
this may cause errors on certain filesystems. 

The data in the buffer is a series of direct structures each containing the following entries: 

unsigned long d fileno; 
unsigned short dreclen; 
unsigned short d namlen; 

char d_name[MAXNAMELEN + 1]; /* see below */ 

The djileno entry is a number which is unique for each distinct file in the filesystem. Files that are linked 
by hard links (see link(2)) have the same d Jileno. The d reclen entry is the length, in bytes, of the direc- 
tory record. The djiame entry contains a null terminated file name. The d_namlen entry specifies the 
length of the file name. Thus the actual size of djiame may vary from 2 to MAXNAME LEN + 1. 

The structures are not necessarily tightly packed. The d reclen entry may be used as an offset from the 
beginning of a direct structure to the next structure, if any. 

Upon return, the actual number of bytes transferred is returned. The current position pointer associated 
with/d is set to point to the next block of entries. The pointer is not necessarily incremented by the number 
of bytes returned by getdirentries. If the value returned is zero, the end of the directory has been reached. 
The current position pointer may be set and retrieved by lseelc(2). Getdirentries writes the position of the 
block read into the location pointed to by basep. It is not safe to set the current position pointer to any 
value other than a value previously returned by lseek(2) or a value previously returned in the location 
pointed to by basep or zero. 

RETURN VALUE 

If successful, the number of bytes actually transferred is returned. Otherwise, a -1 is returned and the glo- 
bal variable errno is set to indicate the error. 

SEE ALSO 

open(2), lseek(2) 

ERRORS 

Getdirentries will fail if one or more of the following are true: 

[EBADF] fd is not a valid file descriptor open for reading. 

DEFAULT] Either buf or basep point outside the allocated address space. 

[EINTR] A read from a slow device was interrupted before any data arrived by the delivery of a 

signal. 

[EIO] An I/O error occurred while reading from or writing to the file system. 
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NAME 

getdomainname, setdomainname - get/set name of current domain 
SYNOPSIS 

getdomainname(name, namelen) 
char *name; 
int namelen; 

setdomainname(name, namelen) 
char *name; 
int namelen; 

DESCRIPTION 

Getdomainname returns the name of the domain for the current processor, as previously set by setdomain- 
name. The parameter namelen specifies the size of the name array. The returned name is null-terminated 
unless insufficient space is provided. 

Setdomainname sets the domain of the host machine to be name, which has length namelen. This call is 
restricted to the super-user and is normally used only when the system is bootstrapped. 

The purpose of domains is to enable two distinct networks that may have host names in common to merge. 
Each network would be distinguished by having a different domain name. At the current time, only the 
yellow pages service makes use of domains. 

RETURN VALUE 

If the call succeeds a value of 0 is returned. If the call fails, then a value of -1 is returned and an error 
code is placed in the global location errno. 

ERRORS 

The following errors may be returned by these calls: 

[EFAULT] The name parameter gave an invalid address. 

[EPERM] The caller was not the super-user. This error only applies to setdomainname. 

BUGS 

Domain names are limited to 255 characters. 
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NAME 

getdtablesize - get descriptor table size 
SYNOPSIS 

nds = getdtablesizeO 
int nds; 

DESCRIPTION 

Each process has a fixed size descriptor table which is guaranteed to have at least 20 slots. The entries in 
the descriptor table are numbered with small integers starting at 0. The call getdtablesize returns the size of 
this table. 

SEE ALSO 

close(2), dup(2), open(2) 
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NAME 

getgid, getegid - get group identity 

SYNOPSIS 

gid = getgid() 
int gid; 

egid = getegid() 
int egid; 

DESCRIPTION 

Getgid returns the real group ID of the current process, getegid the effective group ID. 

The real group ID is specified at login time. 

The effective group ID is more transient, and determines additional access permission during execution of 
a “set-group-ID” process, and it is for such processes that getgid is most useful. 

SEE ALSO 

getuid(2), setregid(2), setgid(3C) 
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NAME 

getgroups - get group access list 
SYNOPSIS 

#include <sys/param.h> 

getgroups(n, gidset) 
int n, * gidset; 

DESCRIPTION 

Getgroups gets the current group access list of the user process and stores it in the array gidset. The 
parameter n indicates the number of entries which may be placed in gidset and getgroups returns the actual 
number of entries placed in the gidset array. No more than NGROUPS, as defined in <sys/param.h>, will 
ever be returned. 

RETURN VALUE 

A return value of greater than zero indicates the number of entries placed in the gidset array. A return 
value of - 1 indicates that an error occurred, and the error code is stored in the global variable errno . 

ERRORS 

The possible errors for getgroup are: 

[EINVAL] The argument n is smaller than the number of groups you are in. 

[EFAULT] The arguments n or gidset specify invalid addresses. 

SEE ALSO 

setgroups(2), initgroups(3) 


36 


Last change: 25 October 1984 


Sun Release 3.0 



GETHOSTID ( 2 ) 


SYSTEM CALLS 


GETHOSTID (2) 


NAME 

gethostid - get unique identifier of current host 

SYNOPSIS 

hostid = gethostidO 
int hostid; 

DESCRIPTION 

Gethostid returns the 32-bit identifier for the current host, which should be unique across all hosts. On the 
Sun, this number is taken from the CPU board’s ID PROM. 

SEE ALSO 

hostid(l) 
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NAME 

gethostname, sethostname - get/set name of current host 
SYNOPSIS 

gethostname(name, namelen) 
char *name; 
int namelen; 

sethostname(name, namelen) 
char *name; 
int namelen; 

DESCRIPTION 

Gethostname returns the standard host name for the current processor, as previously set by sethostname. 
The parameter namelen specifies the size of the name array. The returned name is null-terminated unless 
insufficient space is provided. 

Sethostname sets the name of the host machine to be name, which has length namelen. This call is res- 
tricted to the super-user and is normally used only when the system is bootstrapped. 

RETURN VALUE 

If the call succeeds a value of 0 is returned. If the call fails, then a value of -1 is returned and an error 
code is placed int the global location errno. 

ERRORS 

The following errors may be returned by these calls: 

[EFAULT] The name or namelen parameter gave an invalid address. 

[EPERM] The caller was not the super-user. Note that this error only applies to sethostname . 

SEE ALSO 

gethostid(2) 

BUGS 

Host names are limited to 31 characters. 
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NAME 

getitimer, setitimer - get/set value of interval timer 


SYNOPSIS 

#include <sys/time.h> 

#define ITIMER REAL 
#define ITIMER_VIRTUAL 
#define ITIMERPROF 


0 /* real time intervals */ 

1 I* virtual time intervals *1 

2 I* user and system virtual time *1 


getitimer(which, value) 
int which; 

struct itimerval *value; 

setitimer(which, value, ovalue) 
int which; 

struct itimerval *value, *ovalue; 

DESCRIPTION 

The system provides each process with three interval timers, defined in <sys/time.h>. The getitimer call 
returns the current value for the timer specified in which, while the setitimer call sets the value of a timer 
(optionally returning the previous value of the timer). 

A timer value is defined by the itimerval structure: 

struct itimerval { 

struct timeval itjnterval; I* timer interval */ 
struct timeval itvalue; /* current value */ 

}; 

If it value is non-zero, it indicates the time to the next timer expiration. If itjnterval is non-zero, it 
specifies a value to be used in reloading it value when the timer expires. Setting it_value to 0 disables a 
timer. Setting itjnterval to 0 causes a timer to be disabled after its next expiration (assuming it_value is 
non-zero). 

Time values smaller than the resolution of the system clock are rounded up to this resolution. 

The ITIMER REAL timer decrements in real time. A SIGALRM signal is delivered when this timer 
expires. 

The ITIMER VIRTUAL timer decrements in process virtual time. It runs only when the process is execut- 
ing. A SIGVTALRM signal is delivered when it expires. 

The ITIMER_PROF timer decrements both in process virtual time and when the system is running on 
behalf of the process. It is designed to be used by interpreters in statistically profiling the execution of 
interpreted programs. Each time the ITIMER PROF timer expires, the SIGPROF signal is delivered. 
Because this signal may interrupt in-progress system calls, programs using this timer must be prepared to 
restart interrupted system calls. 

NOTES 

Three macros for manipulating time values are defined in <sysltime.h>. Timer clear sets a time value to 
zero, timerisset tests if a time value is non-zero, and timercmp compares two time values (beware that >= 
and <= do not work with this macro). 

RETURN VALUE 

If the calls succeed, a value of 0 is returned. If an error occurs, the value -1 is returned, and a more precise 
error code is placed in the global variable errno. 

ERRORS 

The possible errors are: 

[EFAULT] The value or ovalue parameter specified a bad address. 
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[EINVAL] A value parameter specified a time which was too large to be handled. 
SEE ALSO 

sigvec(2), gettimeofday(2) 
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NAME 

getpagesize - get system page size 
SYNOPSIS 

pagesize = getpagesizeO 
int pagesize; 

DESCRIPTION 

Getpagesize returns the number of bytes in a page. Page granularity is the granularity of many of the 
memory management calls. 

The page size is a system page size and may not be the same as the underlying hardware page size. 

SEE ALSO 

sbrk(2), pagesize(l) 
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NAME 

getpeemame - get name of connected peer 
SYNOPSIS 

getpeername(s, name, namelen) 
int s; 

struct sockaddr *name; 
int * namelen; 

DESCRIPTION 

Getpeername returns the name of the peer connected to socket s. The namelen parameter should be initial- 
ized to indicate the amount of space pointed to by name . On return it contains the actual size of the name 
returned (in bytes). 

DIAGNOSTICS 

A 0 is returned if the call succeeds, -1 if it fails. 

ERRORS 

The call succeeds unless: 


[EBADF] 

[ENOTSOCK] 

[ENOTCONN] 

[ENOBUFS] 

DEFAULT] 

SEE ALSO 


The argument s is not a valid descriptor. 

The argument s is a file, not a socket 
The socket is not connected. 

Insufficient resources were available in the system to perform the operation. 

The name parameter points to memory not in a valid part of the process address space. 


bind(2), socket(2), getsockname(2) 


BUGS 

Names bound to sockets in the UNIX domain are inaccessible; getpeername returns a zero length name. 
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NAME 

getpgrp - get process group 

SYNOPSIS 

pgrp = getpgrp(pid) 
int pgrp; 
int pid; 

DESCRIPTION 

The process group of the specified process is returned by getpgrp. If pid is zero, the call applies to the 
current process. 

Process groups are used for distribution of signals, and by terminals to arbitrate requests for their input: 
processes which have the same process group as the terminal are foreground and may read, while others 
will block with a signal if they attempt to read. 

This call is thus used by programs such as csh(l) to create process groups in implementing job control. 
The TIOCGPGRP and TIOCSPGRP calls described in tty {A) are used to get/set the process group of the 
control terminal. 

SEE ALSO 

setpgrp(2), getuid(2), tty(4) 
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NAME 

getpid, getppid - get process identification 

SYNOPSIS 

pid = getpid() 
int pid; 

ppid = getppid() 
int ppid; 

DESCRIPTION 

Getpid returns the process ED of the current process. Most often it is used with the host identifier gethos- 
tid( 2) to generate uniquely-named temporary files. 

Getppid returns the process ID of the parent of the current process. 

SEE ALSO 

gethostid(2) 
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NAME 

getpriority, setpriority - get/set program scheduling priority 
SYNOPSIS 

#include <sys/resource.h> 

#define PRIO_PROCESS 0 /* process *1 
#define PRIO_PGRP 1 I* process group */ 

#define PRIO_USER 2 I* user id *1 

prio = getpriority(which, who) 
int prio, which, who; 

setpriority(which, who, prio) 
int which, who, prio; 

DESCRIPTION 

The scheduling priority of the process, process group, or user, as indicated by which and who is obtained 
with the getpriority call and set with the setpriority call. Which is one of PRIOPROCESS, PRIOPGRP, 
or PRIOUSER, and who is interpreted relative to which (a process identifier for PRIO PROCESS, process 
group identifier for PRIO PGRP, and a user ID for PRIO USER). Prio is a value in the range -20 to 20. 
The default priority is 0; lower priorities cause more favorable scheduling. 

The getpriority call returns the highest priority (lowest numerical value) enjoyed by any of the specified 
processes. The setpriority call sets the priorities of all of the specified processes to the specified value. 
Only the super-user may lower priorities. 

RETURN VALUE 

Since getpriority can legitimately return the value -1, it is necessary to clear the external variable errno 
prior to the call, then check it afterward to determine if a -1 is an error or a legitimate value. The setprior- 
ity call returns 0 if there is no error, or -1 if there is. 

ERRORS 

Getpriority and setpriority may return one of the following errors: 

[ESRCH] No process(es) were located using the which and who values specified. 

[EINVAL] Which was not one of PRIO_PROCESS, PRIO_PGRP, or PRIOJJSER. 

In addition to the errors indicated above, setpriority may fail with one of the following errors returned: 

[EACCES] A process was located, but neither its effective nor real user ID matched the effective 
user ID of the caller. 

[EACCES] A non super-user attempted to change a process priority to a negative value. 

SEE ALSO 

nice(l), fork(2), renice(8) 

BUGS 

It is not possible for the process executing setpriority ( ) to lower any other process down to its current 
priority, without requiring superuser privileges. 
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NAME 

getrlimit, setrlimit - control maximum system resource consumption 
SYNOPSIS 

#include <sys/time.h> 

#include <sys/resource.h> 

getrlimit(resource, rip) 
int resource; 
struct rlimit *rlp; 

setrlimit(resource, rip) 
int resource; 
struct rlimit *rlp; 


DESCRIPTION 

Limits on the consumption of system resources by the current process and each process it creates may be 
obtained with the getrlimit call, and set with the setrlimit call. 


The resource parameter is one of the following: 


RLIMITCPU 

RLIMITFSIZE 

RLIMITJDATA 

RLIMITSTACK 

RLIMITCORE 
RLIMIT RSS 


the maximum amount of cpu time (in milliseconds) to be used by each process. 

the largest size, in bytes, of any single file which may be created. 

the maximum size, in bytes, of the data segment for a process; this defines how far a 
program may extend its break with the sbrk( 2) system call. 

the maximum size, in bytes, of the stack segment for a process; this defines how far a 
program’s stack segment may be extended automatically by the system. 

the largest size, in bytes, of a core file which may be created. 

the maximum size, in bytes, a process’s resident set size may grow to. This imposes a 
limit on the amount of physical memory to be given to a process; if memory is tight, 
the system will prefer to take memory from processes which are exceeding their 
declared resident set size. 


A resource limit is specified as a soft limit and a hard limit. When a soft limit is exceeded a process may 
receive a signal (for example, if the cpu time is exceeded), but it will be allowed to continue execution until 
it reaches the hard limit (or modifies its resource limit). The rlimit structure is used to specify the hard and 
soft limits on a resource, 

struct rlimit { 

int rlimcur; /* current (soft) limit */ 

int rlim max; /* hard limit */ 

}; 

Only the super-user may raise the maximum limits. Other users may only alter rlim cur within the range 
from 0 to rlimjnax or (irreversibly) lower rlimjnax. 

An “infinite’ ’ value for a limit is defined as RLIM INFINITY (0x7fffffff). 

Because this information is stored in the per-process information, this system call must be executed directly 
by the shell if it is to affect all future processes created by the shell; limit is thus a built-in command to 
csh( 1). 

The system refuses to extend the data or stack space when the limits would be exceeded in the normal way: 
a break call fails if the data space limit is reached, or the process is killed when the stack limit is reached 
(since the stack cannot be extended, there is no way to send a signal!). 

A file i/o operation which would create a file which is too large will cause a signal SIGXFSZ to be gen- 
erated, this normally terminates the process, but may be caught. When the soft cpu time limit is exceeded, 
a signal SIGXCPU is sent to the offending process. 
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RETURN VALUE 

A 0 return value indicates that the call succeeded, changing or returning the resource limit. A return value 
of — 1 indicates that an error occurred, and an error code is stored in the global location err no. 

ERRORS 

The possible errors are: 

DEFAULT] The address specified for rip is invalid. 

[EPERM] The limit specified to setrlimit would have 

raised the maximum limit value, and the caller is not the super-user. 

SEE ALSO 

csh(l), quota(2) 

BUGS 

There should be limit and unlimit commands in ^(1) as well as in csh. 
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NAME 

getrusage - get information about resource utilization 
SYNOPSIS 

#include <sys/time.h> 

#include <sys/resource.h> 

#define RUSAGE_SELF 0 I* calling process *1 

#define RUSAGE_CHILDREN -1 I* terminated child processes */ 

getrusage(who, rusage) 
int who; 

struct rusage *rusage; 

DESCRIPTION 

Getrusage returns information about the resources utilized by the current process, or all its terminated child 
processes. The who parameter is one of RUSAGE SELF or RUSAGECHILDREN. If rusage is non- 
zero, the buffer it points to will be filled in with the following structure: 

struct rusage { 

struct timeval ruutime; /* user time used */ 

struct timeval ru stime; /* system time used */ 


int 

rumaxrss; 


int 

ruixrss; 

/* integral shared memory size */ 

int 

ru_idrss; 

/* integral unshared data size */ 

int 

ruisrss; 

/* integral unshared stack size */ 

int 

ruminflt; 

/* page reclaims */ 

int 

rujmajflt; 

/* page faults */ 

int 

runswap; 

/* swaps */ 

int 

ruinblock; 

/* block input operations */ 

int 

ruoublock; 

1* block output operations */ 

int 

rumsgsnd; 

/* messages sent */ 

int 

rumsgrcv; 

/* messages received */ 

int 

runsignals; 

/* signals received */ 

int 

runvcsw; 

/* voluntary context switches */ 

int 

runivcsw; 

/* involuntary context switches */ 


}; 

The fields are interpreted as follows: 

rujitime the total amount of time spent executing in user mode. Time is given in 

seconds:microseconds. 

the total amount of time spent in the system executing on behalf of the process(es). 
Time is given in seconds:microseconds. 

the maximum resident set size utilized. Size is given in pages (1 page = 2Kbytes). 

an “integral” value indicating the amount of memory used which was also shared 
among other processes. This value is expressed in units of pages * clock ticks (1 tick = 
1/50 second). The value is calculated by summing the number of shared memory pages 
in use each time the internal system clock ticks, and then averaging over 1 second inter- 
vals. 

ru idrss an integral value of the amount of unshared memory residing in the data segment of a 

process. The value is given in pages * clock ticks. 

ru_isrss an integral value of the amount of unshared memory residing in the stack segment of a 

process. The value is given in pages * clock ticks. 

ru_minflt the number of page faults serviced without any i/o activity; here i/o activity is avoided 


ru_stime 

rumaxrss 
ru ixrss 
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by “reclaiming” a page frame from the list of pages awaiting reallocation, 
rumajflt the number of page faults serviced which required i/o activity. 

ru_nswap the number of times a process was “swapped” out of main memory, 

ruinblock the number of times the file system had to perform input, 

ruoutblock the number of times the file system had to perform output, 

rumsgsnd the number of ipc messages sent, 

rumsgrcv the number of ipc messages received. 
ru_nsignals the number of signals delivered. 

ru nvcsw the number of times a context switch resulted due to a process voluntarily giving up the 

processor before its time slice was completed (usually to await availability of a 
resource). 

runivcsw the number of times a context switch resulted due to a higher priority process becoming 

runnable or because the current process exceeded its time slice. 

NOTES 

The numbers ruinblock and ruoutblock account only for real I/O; data supplied by the caching mechan- 
ism is charged only to the first process to read or write the data. 

ERRORS 

getrusage will fail if: 

[EFAULT] The r usage argument is in an invalid portion of the process’s allocated address space. 

SEE ALSO 

gettimeofday(2), wait(2) 

BUGS 

There is no way to obtain information about a child process which has not yet terminated. 
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NAME 

getsockname - get socket name 
SYNOPSIS 

getsockname(s, name, namelen) 
ints; 

struct sockaddr -name; 
int *namelen; 

DESCRIPTION 

Getsockname returns the current name for the specified socket. The namelen parameter should be initial- 
ized to indicate the amount of space pointed to by name . On return it contains the actual size of the name 
returned (in bytes). 

DIAGNOSTICS 

A 0 is returned if the call succeeds, -1 if it fails. 

ERRORS 

The call succeeds unless: 


[EBADF] 
[ENOTSOCK] 
[ENOBUFS] 
[EFAULT] 
SEE ALSO 


The argument s is not a valid descriptor. 

The argument s is a file, not a socket 

Insufficient resources were available in the system to perform the operation. 

The name parameter points to memory not in a valid part of the process address space. 


bind(2), socket(2), getpeemame(2) 


BUGS 

Names bound to sockets in the UNIX domain are inaccessible; getsockname returns a zero length name. 
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GETSOCKOPT (2) 


NAME 

getsockopt, setsockopt - get and set options on sockets 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

getsockopt(s, level, optname, optval, optlen) 
int s, level, optname; 
char *optval; 
int *optlen; 

setsockopt(s, level, optname, optval, optlen) 
int s, level, optname; 
char * optval; 
int optlen; 

DESCRIPTION 

Getsockopt and setsockopt manipulate options associated with a socket. Options may exist at multiple pro- 
tocol levels; they are always present at the uppermost “socket” level. 

When manipulating socket options the level at which the option resides and the name of the option must be 
specified. To manipulate options at the “socket” level, level is specified as SOL SOCKET. To manipu- 
late options at any other level the protocol number of the appropriate protocol controlling the option is sup- 
plied. For example, to indicate an option is to be interpreted by the TCP protocol, level should be set to the 
protocol number of TCP; see getprotoent(iN). 

The parameters optval and optlen are used to access option values for setsockopt. For getsockopt they 
identify a buffer in which the value for the requested option(s) are to be returned. For getsockopt, optlen is 
a value-result parameter, initially containing the size of the buffer pointed to by optval, and modified on 
return to indicate the actual size of the value returned. If no option value is to be supplied or returned, 
optval may be supplied as 0. 

Optname and any specified options are passed uninterpreted to the appropriate protocol module for 
interpretation. The include file <sysl socket. h> contains definitions for “socket” level options; see 
socket (2). Options at other protocol levels vary in format and name, consult the appropriate entries in (4P). 

RETURN VALUE 

A 0 is returned if the call succeeds, -1 if it fails. 

ERRORS 

The call succeeds unless: 

[EBADF] The argument s is not a valid descriptor. 

[ENOTSOCK] The argument s is a file, not a socket. 

[ENOPROTOOPT] The option is unknown. 

[EFAULT] optval or optlen is not in a valid part of the process address space. 

SEE ALSO 

socket(2), getprotoent(3N) 
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NAME 

gettimeofday, settimeofday - get/set date and time 
SYNOPSIS 

#include <sys/time.h> 

gettimeofday(tp, tzp) 
struct timeval *tp; 
struct timezone *tzp; 

settimeofday(tp, tzp) 
struct timeval *tp; 
struct timezone *tzp; 

DESCRIPTION 

Gettimeofday returns the system’s notion of the current Greenwich time and the current time zone. Time 
returned is expressed in seconds and microseconds since midnight January 1, 1970. 

The structures pointed to by tp and tzp are defined in <sys/time.h> as: 

struct timeval { 

u long tv sec; /* seconds since Jan. 1, 1970 */ 

long tv usec; /* and microseconds *1 

}; 

struct timezone { 

int tzminuteswest; /* of Greenwich */ 

int tz dsttime; I* type of dst correction to apply */ 

}; 

The timezone structure indicates the local time zone (measured in minutes of time westward from 
Greenwich), and a flag that, if nonzero, indicates that Daylight Saving time applies locally during the 
appropriate part of the year. 

If tzp is a zero pointer, the timezone information is not returned or set. 

Only the super-user may set the time of day. 

RETURN 

A 0 return value indicates that the call succeeded. A -1 return value indicates an error occurred, and in this 
case an error code is stored into the global variable errno. 

ERRORS 

The following error codes may be set in errno: 

[EFAULT] An argument address referenced invalid memory. 

[EPERM] A user other than the super-user attempted to set the time. 

SEE ALSO 

date(l), ctime(3) 

BUGS 

Time is never correct enough to believe the microsecond values. There should a mechanism by which, at 
least, local clusters of systems might synchronize their clocks to millisecond granularity. 
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NAME 

getuid, geteuid - get user identity 

SYNOPSIS 

uid = getuidO 
int uid; 

euid = geteuidO 
int euid; 

DESCRIPTION 

Getuid returns the real user ID of the current process, geteuid the effective user ID. 

The real user ID identifies the person who is logged in. The effective user ID gives the process additional 
permissions during execution of “set-user-ID” mode processes, which use getuid to determine the real- 
user-id of the process which invoked them. 

SEE ALSO 

getgid(2), setreuid(2) 
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IOCTL (2) 


NAME 

ioctl - control device 
SYNOPSIS 

#include <sys/ioctl.h> 

ioctl(d, request, argp) 
int d, request; 
char *argp; 

DESCRIPTION 

Ioctl performs a variety of functions on open descriptors. In particular, many operating characteristics of 
character special files (e.g. terminals) may be controlled with ioctl requests. The writeups of various dev- 
ices in section 4 discuss how ioctl applies to them. 

An ioctl request has encoded in it whether the argument is an “in” parameter or “out” parameter, and the 
size of the argument argp in bytes. Macros and defines used in specifying an ioctl request are located in 
the file <sys/ioctl.h > . 

RETURN VALUE 

If an error has occurred, a value of-1 is returned and errno is set to indicate the error. 

If no error has occurred (using a STANDARD device driver), a value of 0 is returned. 

ERRORS 

Ioctl will fail if one or more of the following are true: 

[EBADF] D is not a valid descriptor. 

[ENOTTY] D is not associated with a character special device. 

[ENOTTY] The specified request does not apply to the kind of object which the descriptor d refer- 
ences. 

[EINVAL] Request or argp is not valid. 

SEE ALSO 

execve(2), fcntl(2), mtio(4), tty(4) 
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KELL ( 2 ) 


NAME 

kill - send signal to a process 

SYNOPSIS 

kill(pid, sig) 
int pid, sig; 


DESCRIPTION 

Kill sends the signal sig to a process, specified by the process number pid. Sig may be one of the signals 
specified in sigvec(2), or it may be 0, in which case error checking is performed but no signal is actually 
sent. This can be used to check the validity of pid. 

The sending and receiving processes must have the same effective user ID, otherwise this call is restricted 
to the super-user. A single exception is the signal SIGCONT which may always be sent to any child or 
grandchild of the current process. 

If the process number is 0, the signal is sent to all other processes in the sender’s process group; this is a 
variant of killpg(2). 

If the process number is -1, and the user is the super-user, the signal is broadcast universally except to sys- 
tem processes and the process sending the signal. 

Processes may send signals to themselves. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set 
to indicate the error. 

ERRORS 

Kill will fail and no signal will be sent if any of the following occur 
[EINVAL] Sig is not a valid signal number. 

[ESRCH] No process can be found corresponding to that specified by pid. 

[EPERM] The sending process is not the super-user and its effective user id does not match the 

effective user-id of the receiving process. 


SEE ALSO 

getpid(2), getpgrp(2), killpg(2), sigvec(2) 
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KILLPG ( 2 ) 


NAME 

killpg - send signal to a process group 

SYNOPSIS 

killpg(pgrp, sig) 
int pgrp, sig; 

DESCRIPTION 

Killpg sends the signal sig to the process group pgrp . See sigvec (2) for a list of signals. 

The sending process and members of the process group must have the same effective user ID, otherwise 
this call is restricted to the super-user. As a single special case the continue signal SIGCONT may be sent 
to any process which is a descendant of the current process. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and the global 
variable errno is set to indicate the error. 

ERRORS 

Killpg will fail and no signal will be sent if any of the following occur: 

[EINVAL] Sig is not a valid signal number. 

[ESRCH] No process were found in the specified process group. 

[EPERM] The sending process is not the super-user and one or more of the target processes has an 

effective user ID different from that of the sending process. 

SEE ALSO 

kill(2), getpgrp{2), sigvec(2) 
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NAME 

link - make a hard link to a file 

SYNOPSIS 

Iink(namel, name2) 
char * namel, *name2; 

DESCRIPTION 

A hard link to namel is created; the link has the name name2 . Namel must exist. 

With hard links, both namel and name2 must be in the same file system. Unless the caller is the super- 
user, namel must not be a directory. Both the old and the new link share equal access and rights to the 
underlying object. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set 
to indicate the error. 

ERRORS 

Link will fail and no link will be created if one or more of the following are true: 

[EPERM] Either pathname contains a byte with the high-order bit set. 

[ENAMETOOLONG] 

Either pathname was too long. 

[ENOTDIR] A component of either path prefix is not a directory. 

[ENOENT] A component of either path prefix does not exist. 

[EACCES] A component of either path prefix denies search permission. 

[ENOENT] The file named by namel does not exist. 

[EEXISTJ The link named by name2 does exist. 

[EPERM] The file named by namel is a directory and the effective user ID is not super-user. 

[EXDEV] The link named by name2 and the file named by namel are on different file systems. 

[EACCES] The requested link requires writing in a directory with a mode that denies write permis- 

sion. 

[EROFS] The requested link requires writing in a directory on a read-only file system. 

[EFAULT] One of the pathnames specified is outside the process’s allocated address space. 

[ELOOP] Too many symbolic links were encountered in translating the pathname. 

[ENOSPC] The directory in which the entry for the new link is being placed cannot be extended 

because there is no space left on the file system containing the directory. 

[EDQUOT] The directory in which the entry for the new link is being placed cannot be extended 
because the user’s quota of disk blocks on the file system containing the directory has 
been exhausted. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

SEE ALSO 

symlink(2), unlink(2) 
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LISTEN (2) 


NAME 

listen - listen for connections on a socket 

SYNOPSIS 

listen(s, backlog) 
int s, backlog; 

DESCRIPTION 

To accept connections, a socket is first created with socket (2), a backlog for incoming connections is 
specified with listen (2) and then the connections are accepted with accept (2). The listen call applies only 
to sockets of type SOCK STREAM or SOCKSEQPACKET. 

The backlog parameter defines the maximum length the queue of pending connections may grow to. If a 
connection request arrives with the queue full the client will receive an error with an indication of 
ECONNREFU SED. 

RETURN VALUE 

A 0 return value indicates success; -1 indicates an error. 

ERRORS 

The call fails if: 

[EBADF] The argument s is not a valid descriptor. 

[ENOTSOCK] The argument s is not a socket 

[EOPNOTSUPP] The socket is not of a type that supports the operation listen. 

SEE ALSO 

accept(2), connect(2), socket(2) 

BUGS 

The backlog is currently limited (silently) to 5. 
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LSEEK ( 2 ) 


NAME 

lseek, tell - move read/write pointer 
SYNOPSIS 

#define L_SET 0 /* set the seek pointer *1 

#define L_INCR 1 I* increment the seek pointer */ 

#define L XTND 2 /* extend the file size *1 

pos = lseek(d, offset, whence) 

int pos; 

intd; 

long offset; 
int whence; 

DESCRIPTION 

The descriptor d refers to a file or device open for reading and/or writing. Lseek sets the file pointer of d as 
follows: 

If whence is LSET, the pointer is set to offset bytes. 

If whence is L INCR, the pointer is set to its current location plus offset. 

If whence is L XTND, the pointer is set to the size of the file plus offset. 

Upon successful completion, the resulting pointer location as measured in bytes from beginning of the file 
is returned. Some devices are incapable of seeking. The value of the pointer associated with such a device 
is undefined. 

The obsolete function tell(fildes) is identical to lseek(fildes, OL, L INCR). 

NOTES 

Seeking far beyond the end of a file, then writing, creates a gap or “hole”, which occupies no physical 
space and reads as zeros. 

RETURN VALUE 

Upon successful completion, a non-negative integer, the current file pointer value, is returned. Otherwise, 
a value of -1 is returned and err no is set to indicate the error. 

ERRORS 

Lseek will fail and the file pointer will remain unchanged if: 

[EBADF] Fildes is not an open file descriptor. 

[ESPEPE] Fildes is associated with a pipe or a socket. 

[EINVAL] Whence is not a proper value. 

[EINVAL] The resulting file pointer would be negative. 

SEE ALSO 

dup(2), open(2) 
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MKDIR (2) 


NAME 

mkdir - make a directory file 

SYNOPSIS 

mkdir(path, mode) 
char *path; 
int mode; 

DESCRIPTION 

Mkdir creates a new directory file with name path. The mode of the new file is initialized from mode. The 
protection part of the mode is modified by the process’s mode mask; see umask( 2). 

The directory’s owner ID is set to the process’s effective user ID. The directory’s group ID is set to that of 
the parent directory in which it is created. 

The low-order 9 bits of mode are modified by the process’s file mode creation mask: all bits set in the 
process’s file mode creation mask are cleared. See umask{ 2). 

RETURN VALUE 

A 0 return value indicates success. A -1 return value indicates an error, and an error code is stored in 
errno. 

ERRORS 

Mkdir will fail and no directory will be created if: 

[EPERM] The process’s effective user ED is not super-user. 

[EPERM] The path argument contains a byte with the high-order bit set. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] A component of the path prefix does not exist 

[EROFS] The named file resides on a read-only file system. 

[EEXIST] The named file exists. 

[EFAULT] Path points outside the process’s allocated address space. 

[ELOOP] Too many symbolic links were encountered in translating the pathname. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

[ENAMETOOLONG] 

The pathname was too long. 

[EACCES] A component of the path prefix denies search permission. 

[ENOSPC] The directory in which the entry for the new file is being placed cannot be extended 

because there is no space left on the file system containing the directory. 

[ENOSPC] The new directory cannot be created because there is no space left on the file system 
which will contain the directory. 

[ENOSPC] There are no free inodes on the file system on which the file is being created. 

[EDQUOT] The directory in which the entry for the new file is being placed cannot be extended 

because the user’s quota of disk blocks on the file system containing the directory has 
been exhausted. 

[EDQUOT] The new directory cannot be created becaue the user’s quota of disk blocks on the file 
system which will contain the directory has been exhausted. 

[EDQUOT] The user’s quota of inodes on the file system on which the file is being created has been 
exhausted. 
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SEE ALSO 

chmod(2), stat(2), umask(2) 
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MKNOD (2) 


NAME 

mknod - make a special file 
SYNOPSIS 

mknod(path, mode, dev) 
char *path; 
int mode, dev; 

DESCRIPTION 

Mknod creates a new file whose name is path. The mode of the new file (including special file bits) is ini- 
tialized from mode. The protection part of the mode is modified by the process’s mode mask; see 
umask( 2). The first block pointer of the i-node is initialized from dev and is used to specify which device 
the special file refers to. 

If mode indicates a block or character special file, dev is a configuration dependent specification of a char- 
acter or block I/O device. If mode does not indicate a block special or character special device, dev is 
ignored. 

Mknod may be invoked only by the super-user. 

RETURN VALUE 

Upon successful completion a value of 0 is returned. Otherwise, a value of-1 is returned and errno is set 
to indicate the error. 

ERRORS 

Mknod will fail and the file mode will be unchanged if: 

[EPERM] The process’s effective user ID is not super-user. 

[EISDIR] The specified mode would have created a directory. 

[EPERM] The pathname contains a character with the high-order bit set 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] A component of the path prefix does not exist. 

[EROFS] The named file resides on a read-only file system. 

[EEXIST] The named file exists. 

DEFAULT] Path points outside the process’s allocated address space. 

[ELOOP] Too many symbolic links were encountered in translating the pathname. 

[ENAMETOOLONG] 

The pathname was too long. 

[EACCES] A component of the path prefix denies search permission. 

[ENOSPC] The directory in which the entry for the new file is being placed cannot be extended 

because there is no space left on the file system containing the directory. 

[ENOSPC] There are no free inodes on the file system on which the file is being created. 

[EDQUOT] The directory in which the entry for the new file is being placed cannot be extended 

because the user’s quota of disk blocks on the file system containing the directory has 
been exhausted. 

[EDQUOT] The user’s quota of inodes on the file system on which the file is being created has been 
exhausted. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

SEE ALSO 

chmod(2), stat(2), umask(2) 
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NAME 

mmap - map pages of memory 
SYNOPSIS 

#include <sys/mman.h> 

#include <sys/types.h> 

mmap(addr, Ien, prot, share, fd, off) 
caddr_t addr; int len, prot, share, fd; off_t off; 

DESCRIPTION 

This call is not completely implemented in 4.2 BSD. 

Mmap maps the pages starting at addr and continuing for len bytes from the object represented by the 
descriptor fd, at the current file position of offset off. The parameter share specifies whether modifications 
made to this mapped copy of the page are to be kept private or are to be shared with other references. The 
parameter prot specifies the accessibility of the mapped pages. The addr and len parameters and the sum 
of the current position in fd and the off parameters must be multiples of the page size (found using the get- 
page size (2) call). 

Pages are automatically unmapped at close . 

When called to map an area of 128k or more, the kernel will RELEASE the swap area previously associ- 
ated with the mapped area. When this area is unmapped (using munmap), pages within the area are 
marked invalid. When using valloc and malloc to allcoate such areas, do not free the area as you normally 
would. Instead, call valloc or malloc. 

RETURN VALUE 

The call returns 0 on success, -1 on failure. 

ERRORS 

The mmap call will fail if: 

[EINVAL] The argument address or length is not a multiple of the page size as returned by 
getpagesize (2), or the length is negative. 

[EINVAL] The entire range of pages specified in the call is not part of data space. 

[EINVAL] The specified fd does not refer to a character special device which supports mapping (e.g. a 
frame buffer). 

[EINVAL] The specified fd is not open for reading and read access is requested, or not open for writing 
when write access is requested. 

[EINVAL] The sharing mode was not specified as MAPSHARED. 

SEE ALSO 

getpagesize(2), munmap(2), close(2) 

BUGS 

The kernel may panic when more than 128k of memory has been unmapped with munmap and mmap is 
subsequently called with an incorrect length value. 
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NAME 

mount - mount file system 
SYNOPSIS 

#include <sys/mount.h> 

mount(type, dir, flags, data) 

int type; 

char *dir; 

int flags; 

caddr_t data; 

DESCRIPTION 

mount attaches a file system to a directory. After a successful return, references to directory dir will refer 
to the root directory on the newly mounted file system. Dir is a pointer to a null-terminated string contain- 
ing a path name. Dir must exist already, and must be a directory. Its old contents are inaccessible while 
the file system is mounted. 

The flags argument determines whether the file system can be written on, and if set-uid execution is 
allowed. Physically write-protected and magnetic tape file systems must be mounted read-only or errors 
will occur when access times are updated, whether or not any explicit write is attempted. 

Type indicates the type of the filesystem. It must be one of the types defined in mount, h. Data is a pointer 
to a structure which contains the type specific arguments to mount. Below is a list of the filesystem types 
supported and the type specific arguments to each: 

MOUNTJJFS 

struct ufs args { 

char *fspec; I* Block special file to mount */ 

1 ; 

MOUNT_NFS 

#include <nfs/nfs.h> 

#include <netinet/in.h> 

struct nfsargs { 

struct sockaddr in *addr; /* file server address */ 


fhandlet 

*fh; 

1* File handle to be mounted */ 

int 

flags; 

/* flags */ 

int 

wsize; 

/* write size in bytes *1 

int 

rsize; 

I* read size in bytes */ 

int 

timeo; 

/* initial timeout in .1 secs */ 

int 

retrans; 

/* times to retry send */ 


}; 

RETURN VALUE 

Mount returns 0 if the action occurred, and -1 if special is inaccessible or not an appropriate file, if name 
does not exist, if special is already mounted, if name is in use, or if there are already too many file systems 
mounted. 


ERRORS 

Mount will fail when one of the following occurs: 


[EPERM] 

[ENOENT] 

[ENOTBLK] 

[ENXIO] 

[EPERM] 


The caller is not the super-user. 

Special does not exist. 

Special is not a block device. 

The major device number of special is out of range (this indicates no device driver exists 
for the associated hardware). 

The pathname contains a character with the high-order bit set. 
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[ENOTDIR] 

[EBUSY] 

[EBUSY] 

[EBUSY] 


A component of the path prefix in name is not a directory. 

Dir is not a directory, or another process currently holds a reference to it. 

No space remains in the mount table. 

The super block for the file system had a bad magic number or an out of range block 
size. 


[EBUSY] Not enough memory was available to read the cylinder group information for the file 

system. 


[EIO] An VO error occurred while reading the super block or cylinder group information. 

[ENOTDIR] A component of the path prefix in special or name is not a directory. 

[EPERM] The pathname of special or name contains a character with the high-order bit set. 

[ENAMETOOLONG] 

The pathname of special or name was too long. 


[ENOENT] 

[EACCES] 

[EFAULT] 

[ELOOP] 


Special or name does not exist 

Search permission is denied for a component of the path prefix of special or name . 

Special or name points outside the process’s allocated address space. 

Too many symbolic links were encountered in translating the pathname of special or 
name. 


[EIO] An I/O error occurred while reading from or writing to the file system. 

SEE ALSO 

nfsmount(2), unmount(2), mount(8) 

BUGS 

The error codes are in a state of disarray; too many errors appear to the caller as one value. 
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NAME 

munmap - unmap pages of memory 

SYNOPSIS 

#include <mman.h> 

munmap(addr, len) 
caddr_t addr; inf len; 

DESCRIPTION 

This call is not completely implemented in 4.2 BSD. 

Munmap causes the pages starting at addr and continuing for len bytes to refer to private pages which will 
be initialized to zero on reference. 

RETURN VALUE 

The call returns -1 on error, 0 on success. 

ERRORS 

The call fails if any of the following: 

[EINVAL] The argument address or length is not a multiple of the page size as returned by 
getpagesize (2), or the length is negative. 

[EINVAL] The entire range of pages specified in the call is not part of data space. 

SEE ALSO 

brk (2), mmap(2), close(2) 


66 


Last change: 20 August 1985 


Sun Release 3.0 



NFSMOUNT ( 2 ) 


SYSTEM CALLS 


NFSMOUNT (2) 


NAME 

nfsmount - obsoleted by mount (2) 

DESCRIPTION 

nfsmount has been superceded by mount (2), see page 64 for a description of mount and its use in mounting 
NFS file systems. 
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NAME 

nfssvc, asyncdaemon - NFS daemons 

SYNOPSIS 

nfssvc(sock) 
int sock; 

async_daemon() 

DESCRIPTION 

Nfssvc starts an NFS daemon listening on socket sock. The socket must be AFJNET, and 
SOCK DGRAM (protocol UDP/IP). The system call will return only if the process is killed. 

Async daemon implements the NFS daemon that handles asynchronous I/O for an NFS client The system 
call never returns. 

BUGS 

These two system calls allow kernel processes to have user context. 

SEE ALSO 

nfs(4), mountd(8) 
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NAME 

open - open or create a file for reading or writing 

SYNOPSIS 

#include <sys/file.h> 

open(path, flags, mode) 
char *path; 
int flags, mode; 


DESCRIPTION 

Open opens the file path for reading and/or writing, as specified by the flags argument and returns a 
descriptor for that file. The flags argument may indicate the file is to be created if it does not already exist 
(by specifying the OCREAT flag), in which case the file is created with mode mode as described in 
chmod(2) and modified by the process’ umask value (see umask( 2)). 

path is the address of a string of ASCII characters representing a pathname, terminated by a null character. 
If the path is a null string, the kernel maps this null pathname to V, the current directory. 

The flags specified are formed by or’ing the following values 


ORDONLY 

OWRONLY 

ORDWR 

ONDELAY 

OAPPEND 

OCREAT 

OTRUNC 

OEXCL 


open for reading only 
open for writing only 
open for reading and writing 
do not block on open 
append on each write 
create file if it does not exist 
truncate size to 0 
error if create and file exists 


Opening a file with O APPEND set causes each write on the file to be appended to the end. If O TRUNC 
is specified and the file exists, the file is truncated to zero length. If 0_EXCL is set with O CREAT, then 
if the file already exists, the open returns an error. This can be used to implement a simple exclusive 
access locking mechanism. If the O NDELAY flag is specified and the open call would result in the pro- 
cess being blocked for some reason (e.g. waiting for carrier on a dialup line), the open returns immediately. 
The first time the process attempts to perform i/o on the open file it will block (not currently implemented). 

Upon successful completion a non-negative integer termed a file descriptor is returned. The file pointer 
used to mark the current position within the file is set to the beginning of the file. 

The new descriptor is set to remain open across execve system calls; see close (2). 

There is a system enforced limit on the number of open file descriptors per process, whose value is returned 
by the getdtablesize{ 2) call. 


RETURN VALUE 

The value -1 is returned if an error occurs, and external variable errno is set to indicate the cause of the 
error. Otherwise a non-negative numbered file descriptor for the new open file is returned. 


ERRORS 

Open fails if: 

[EPERM] 

[ENOTDIR] 

[ENOENT] 

[EACCES] 

[EACCES] 

[EISDIR] 

[EROFS] 


The pathname contains a character with the high-order bit set. 

A component of the path prefix is not a directory. 

0_CREAT is not set and the named file does not exist. 

A component of the path prefix denies search permission. 

The required permissions (for reading and/or writing) are denied for the named file. 

The named file is a directory, and the arguments specify it is to be opened for writing. 
The named file resides on a read-only file system, and the file is to be opened for writing. 
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[EMFILE] {OPEN MAX} file descriptors are currently open. 

[ETXTBSY] The file is a pure procedure (shared text) file that is being executed and the open call 
requests write access. 

[EFAULT] Path points outside the process’s allocated address space. 

[ELOOP] Too many symbolic links were encountered in translating the pathname. 

[EEXIST] O EXCL and OCREAT were both specified and the file does not exist 

[ENXIO] The O NDELAY flag is given, and the file is a communications device on which there 

is no carrier present. 

[EOPNOTSUPP] An attempt was made to open a socket (not currently implemented). 

[ENOENT] A component of the path name which must exist does not exist. 

[ENAMETOOLONG] 

The pathname was too long. 

[EACCES] O CREAT is specified, the file does not exist and the directory in which it is to be 
created does not permit writing. 

[ENXIO] The named file is a character special or block special file, and the device associated with 

this special file does not exist 

[ENFILE] The system file table is full. 

[ENOSPC] The directory in which the entry for the new file is being placed cannot be extended 
because there is no space left on the file system containing the directory, the file does not 
exist and O CREAT is specified. 

[ENOSPC] There are no free inodes on the file system on which the file is being created, the file 
does not exist, and O CREAT is specified. 

[EDQUOT] The directory in which the entry for the new file is being placed cannot be extended 
because the user’s quota of disk blocks on the file system containing the directory has 
been exhausted, the file does not exist and O CREAT is specified. 

[EDQUOT] The user’s quota of inodes on the file system on which the file is being created has been 
exhausted, the file does not exist, and O CREAT is specified. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

SEE ALSO 

chmod(2), close(2), dup(2), lseek(2), read(2), write(2), umask(2) 
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NAME 

pipe - create an interprocess communication channel 

SYNOPSIS 

pipe(fildes) 
int fildes[2]; 

DESCRIPTION 

The pipe system call creates an I/O mechanism called a pipe. The file descriptors returned can be used in 
read and write operations. When the pipe is written using the descriptor jildes[Y\ up to 4096 bytes of data 
are buffered before the writing process is suspended. A read using the descriptor fildes[0] will pick up the 
data. 

It is assumed that after the pipe has been set up, two (or more) cooperating processes (created by subse- 
quent fork calls) will pass data through the pipe with read and write calls. 

The shell has a syntax to set up a linear array of processes connected by pipes. 

Read calls on an empty pipe (no buffered data) with only one end (all write file descriptors closed) returns 
an end-of-file. 

Pipes are really a special case of the socketpair{2) call and, in fact, are implemented as such in the system. 
A signal is generated if a write on a pipe with only one end is attempted. 

RETURN VALUE 

The function value zero is returned if the pipe was created; -1 if an error occurred. 

ERRORS 

The pipe call will fail if: 

[EMFILE] Too many descriptors are active. 

[EFAULT] The fildes buffer is in an invalid area of the process’s address space. 

[ENFILE] The system file table is full. 

SEE ALSO 

sh(l), read(2), write(2), fork(2), socketpair(2) 

BUGS 

Should more than 4096 bytes be necessary in any pipe among a loop of processes, deadlock will occur. 
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NAME 

profil - execution time profile 
SYNOPSIS 

profiI(buff, bufsiz, offset, scale) 
char *buff; 

int bufsiz, offset, scale; 

DESCRIPTION 

Buff points to an area of core whose length (in bytes) is given by bufsiz. After this call, the user’s program 
counter (pc) is examined each clock tick (20 milliseconds); offset is subtracted from it, and the result multi- 
plied by scale. If the resulting number corresponds to a word inside buff, that word is incremented. 

The scale is interpreted as an unsigned, fixed-point fraction with binary point at the left: 0x10000 gives a 
1-1 mapping of pc’s to words in buff; 0x8000 maps each pair of instruction words together. 0x2 maps all 
instructions onto the beginning of buff (producing a non-interrupting core clock). 

Profiling is turned off by giving a scale of 0 or 1. It is rendered ineffective by giving a bufsiz of 0. 
Profiling is turned off when an execve is executed, but remains on in child and parent both after a fork. 
Profiling is turned off if an update in buff would cause a memory fault 

RETURN VALUE 

A 0, indicating success, is always returned. 

SEE ALSO 

gprof(l), setitimer(2), monitor(3) 
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NAME 

ptrace - process trace 

SYNOPSIS 

#include <signal.h> 

#include <sys/ptrace.h> 

#include <sys/wait.h> 

ptrace(request, pid, addr, data, addr2) 

enum ptracereq request; 

int pid; 

char *addr; 

int data; 

char *addr2; 

DESCRIPTION 

Ptrace provides a means by which a process may control the execution of another process, and examine 
and change its core image. Its primary use is for the implementation of breakpoint debugging. There are 
five arguments whose interpretation depends on the request argument Generally, pid is the process ED of 
the traced process. A process being traced behaves normally until it encounters some signal whether inter- 
nally generated like ‘illegal instruction’ or externally generated like ‘interrupt’. See sigvec( 2) for the list. 
Then the traced process enters a stopped state and the tracing process is notified via wait( 2). When the 
traced process is in the stopped state, its core image can be examined and modified using ptrace. If 
desired, another ptrace request can then cause the traced process either to terminate or to continue, possibly 
ignoring the signal. 

Note that several different values of the request argument can make ptrace return data values — since -1 is 
a possibly legitimate value, to differentiate between -I as a legitimate value and -1 as an error code, you 
should clear the errno global error code before doing a ptrace call, and then check the value of errno after- 
wards. 

The value of the request argument determines the precise action of the call: 

PTRACEJTRACEME 

This request is the only one used by the traced process; it declares that the process is to be traced by 
its parent. All the other arguments are ignored. Peculiar results will ensue if the parent does not 
expect to trace the child. 

PTRACEPEEKTEXT, PTRACEPEEKDATA 

The word in the traced process’s address space at addr is returned. If the instruction and data spaces 
are separate (for example, historically on a PDP-11), request PTRACE PEEKTEXT indicates instruc- 
tion space while PTRACE PEEKDATA indicates data space. Addr must be even, the child must be 
stopped and the input data and addr2 are ignored. 

PTRACEPEEKU SER 

The word of the system’s per-process data area corresponding to addr is returned. Addr must be a 
valid offset within the kernel’s per-process data pages. This space contains the registers and other 
information about the process; its layout corresponds to the user structure in the system. 

PTRACEPOKETEXT, PTRACEPOKEDATA 

The given data is written at the word in the process’s address space corresponding to addr, which 
must be even. No useful value is returned. If the instruction and data spaces are separate request 
PTRACE_PEEKTEXT indicates instruction space while PTRACE_PEEKDATA indicates data space. 
The PTRACE_POKETEXT request must be used to write into a process’s text space even if the 
instruction and data spaces are not separate. Attempts to write in a pure text space fail if another pro- 
cess is executing the same file. 

PTRACEPOKEUSER 

The process’s system data is written, as it is read with request FIRACE PEEKUSER. Only a few 
locations can be written in this way: the general registers, the floating point status and registers, and 
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certain bits of the processor status word. 

PTRACECONT 

The data argument is taken as a signal number and the child’s execution continues at location addr as 
if it had incurred that signal. Normally the signal number will be either 0 to indicate that the signal 
that caused the stop should be ignored, or that value fetched out of the process’s image indicating 
which signal caused the stop. If addr is (int *)1 then execution continues from where it stopped. 
PTRACEKILL 

The traced process terminates. 

PTRACESINGLESTEP 

Execution continues as in request PTRACE CONT; however, as soon as possible after execution of at 
least one instruction, execution stops again. The signal number from the stop is SIGTRAP. On the 
Sun and VAX-1 1 the T-bit is used and just one instruction is executed. This is part of the mechanism 
for implementing breakpoints. 

PTRACEATT ACH 

Attach to the process identified by the pid argument and begin tracing it. Process pid does not have to 
be a child of the requestor, but the requestor must have permission to send process pid a signal and the 
effective userids of the requesting process and process pid must match. 

PTRACEDETACH 

Detach the process being traced. Process pid is no longer being traced and continues its execution. 
The data argument is taken as a signal number and the process continues at location addr 
as if it had incurred that signal. 

PTRACEGETREGS 

The traced process’s registers are returned in a structure pointed to by the addr argument The regis- 
ters include the general purpose registers, the program counter and the program status word. The 
‘regs’ structure defined in <machine/reg.h> describes the data that is returned. 

PTRACESETREGS 

The traced process’s registers are written from a structure pointed to by the addr argument. The regis- 
ters include the general purpose registers, the program counter and the program status word. The 
‘regs’ structure defined in <machine/reg.h> describes the data that is set. 

PTRACEREADTEXT, PTRACEREADDATA 

Read data from the address space of the traced process. If the instruction and data spaces are separate, 
request PTRACE READTEXT indicates instruction space while PTRACE READDATA indicates 
data space. The addr argument is the address within the traced process from where the data is read, 
the data argument is the number of bytes to read, and the addr2 argument is the address within the 
requesting process where the data is written. 

PTRACEWRITETEXT, PTRACEWRITEDATA 

Write data into the address space of the traced process. If the instruction and data spaces are separate, 
request PTRACE READTEXT indicates instruction space while PTRACE_READDATA indicates 
data space. The addr argument is the address within the traced process where the data is written, the 
data argument is the number of bytes to write, and the addr2 argument is the address within the 
requesting process from where the data is read. 

As indicated, these calls (except for requests PTRACE TRACEME and PTRACE ATTACH) can be used 
only when the subject process has stopped. The wait call is used to determine when a process stops; in 
such a case the ‘termination’ status returned by wait has the value WSTOPPED to indicate a stop rather 
than genuine termination. 

To forestall possible fraud, ptrace inhibits the set-user-id and set-group-id facilities on subsequent 
execve (2) calls. If a traced process calls execve, it will stop before executing the first instruction of the 
new image showing signal SIGTRAP. 
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On the Sun and VAX-11, ‘word’ also means a 32-bit integer; the ‘even’ restriction does not apply on the 
VAX-11. 


RETURN VALUE 

In general, a 0 value is returned if the call succeeds. Note that this is not always true because requests such 
as PTRACEPEEKTEXT and PTRACE PEEKDATA return legitimate values. If the call fails then a -1 is 
returned and the global variable errno is set to indicate the error. 


ERRORS 

[EINVAL] The request code is invalid. 

[EINVAL] The specified process does not exist 
[EINVAL] The given signal number is invalid. 

[EFAULT] The specified address is out of bounds. 

[EPERM] The specified process cannot be traced. 

SEE ALSO 

wait(2), sigvec(2), adb(lS) 

BUGS 

Ptrace is unique and arcane; it should be replaced with a special file which can be opened and read and 
written. The control functions could then be implemented with ioctl( 2) calls on this file. This would be 
simpler to understand and have much higher performance. 

The requests PTRACETRACEME thru PTRACE SINGLESTEP are standard UNIX ptrace requests. 
The requests PTRACE ATTACH thru PTRACE_READDATA and the fifth argument addr2, are unique 
to Sun UNIX. 


The request PTRACE TRACEME should be able to specify signals which are to be treated normally and 
not cause a stop. In this way, for example, programs with simulated floating point (which use ‘illegal 
instruction’ signals at a very high rate) could be efficiently debugged. 

The error indication, -1, is a legitimate function value; errno, see intro(2), can be used to clarify. 

It should be possible to stop a process on occurrence of a system call; in this way a completely controlled 
environment could be provided. 
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NAME 

quota - manipulate disk quotas 
SYNOPSIS 

#include <sys/quota.h> 

quota(cmd, uid, arg, addr) 
int cmd, uid, arg; 
caddr_t addr; 

DESCRIPTION 

N.B.: This call is not implemented in the current version of the system. 

The quota call manipulates disk quotas for file systems which have had quotas enabled with setquota( 2). 
The cmd parameter indicates a command to be applied to the user ID uid. Arg is a command specific argu- 
ment and addr is the address of an optional, command specific, data structure which is copied in or out of 
the system. The interpretation of arg and addr is given with each command below. 

QSETDL1M 

Set disc quota limits and current usage for the user with ID uid. Arg is a major-minor device indi- 
cating a particular file system. Addr is a pointer to a struct dqblk structure (defined in 
<sys/quota.h>). This call is restricted to the super-user. 

QGETDLIM 

Get disc quota limits and current usage for the user with ID uid. The remaining parameters are as 
for QSETDLIM. 

QSETDUSE 

Set disc usage limits for the user with ID uid. Arg is a major-minor device indicating a particular 
file system. Addr is a pointer to a struct dqusage structure (defined in <sys/quota.h>). This call is 
restricted to the super-user. 

QSYNC 

Update the on-disc copy of quota usages. The uid, arg, and addr parameters are ignored. 
QSETUID 

Change the calling process’s quota limits to those of the user with ID uid. The arg and addr 
parameters are ignored. This call is restricted to the super-user. 

QSETWARN 

Alter the disc usage warning limits for the user with ID uid. Arg is a major-minor device indicat- 
ing a particular file system. Addr is a pointer to a struct dqwam structure (defined in 
<sys/quota.h>). This call is restricted to the super-user. 

QDOWARN 

Warn the user with user ID uid about excessive disc usage. This call causes the system to check 
its current disc usage information and print a message on the terminal of the caller for each file 
system on which the user is over quota. If the arg parameter is specified as NODEV, all file sys- 
tems which have disc quotas will be checked. Otherwise, arg indicates a specific major-minor 
device to be checked. This call is restricted to the super-user. 

RETURN VALUE 

A successful call returns 0 and, possibly, more information specific to the cmd performed; when an error 
occurs, the value -1 is returned and errno is set to indicate the reason. 

ERRORS 

A quota call will fail when one of the following occurs: 

[EINVAL] Cmd is invalid. 

[ESRCH] No disc quota is found for the indicated user. 

[EPERM] The call is priviledged and the caller was not the super-user. 
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[EINVAL] The arg parameter is being interpreted as a major-minor device and it indicates an 
unmounted file system. 

[EFAULT] An invalid addr is supplied; the associated structure could not be copied in or out of the 
kernel. 

[EUSERS] The quota table is full. 

SEE ALSO 

setquota(2), quotaon(8), quotacheck(8) 

BUGS 

There should be someway to integrate this call with the resource limit interface provided by setrlimit(2) 
and getrlimit(2). 

The Australian spelling of disk is used throughout the quota facilities in honor of the implementors. 
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NAME 

quotactl - manipulate disk quotas 
SYNOPSIS 

#include <ufs/quota.h> 

quotactl(cmd, special, uid, addr) 

int and; 

char *special; 

int mid; 

caddrt addr; 

DESCRIPTION 

The quotactl call manipulates disk quotas. The cmd parameter indicates a command to be applied to the 
user ID uid. Special is a pointer to a null-terminated string containing the path name of the block special 
device for the file system being manipulated. The block special device must be mounted. Addr is the 
address of an optional, command specific, data structure which is copied in or out of the system. The 
interpretation of addr is given with each command below. 

QQUOTAON 

Turn on quotas for a file system. Addr is a pointer to a null terminated string containing the path 
name of file containing the quotas for the file system. The quota file must exist; it is normally 
created with the quotacheck(8) program. This call is restricted to the super-user. 

Q_QUOTAOFF 

Turn off quotas for a file system. This call is restricted to the super-user. 

QGETQUOTA 

Get disk quota limits and current usage for user uid. Addr is a pointer to a street dqblk structure 
(defined in <ufs/quota.h>). Only the super-user may get the quotas of a user other than himself. 
QSETQUOTA 

Set disk quota limits and current usage for user uid. Addr is a pointer to a struct dqblk structure 
(defined in <ufs/quota.h>). This call is restricted to the super-user. 

QSETQLIM 

Set disk quota limits for user uid. Addr is a pointer to a struct dqblk structure (defined in 
<ufs/quota.h>). This call is restricted to the super-user. 

QSYNC 

Update the on-disk copy of quota usages. This call is restricted to the super-user. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of-1 is returned and errno is set 
to indicate the error. 

ERRORS 

A quotactl call will fail when one of the following occurs: 

[EINVAL] Cmd is invalid. 

[EPERM] The call is privileged and the caller was not the super-user. 

[EINVAL] The special parameter is not a mounted file system or is a mounted file system without 
quotas enabled. 

[ENOTBLK] The special parameter is not a block device. 

[EFAULT] An invalid addr is supplied; the associated structure could not be copied in or out of the 
kernel. 

[EINVAL] The addr parameter is being interpreted as the path of a quota file which exists but is 
either not a regular file or is not on the file system pointed to by the special parameter. 
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[EUSERS] The quota table is full. 

SEE ALSO 

quotaon(8), quotacheck(8) 

BUGS 

There should be some way to integrate this call with the resource limit interface provided by setrlimit( 2) 
and getrlimit(2). Incompatible with Melbourne quotas. 
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NAME 

read, readv - read input 
SYNOPSIS 

cc = read(d, buf, nbytes) 
int cc, d; 
char *buf; 
int nbytes; 

#include <sys/types.h> 

#include <sys/uio.h> 

cc = readv(d, iov, iovcnt) 
int cc, d; 

struct iovec *iov; 
int iovcnt; 

DESCRIPTION 

Read attempts to read nbytes of data from the object referenced by the descriptor d into the buffer pointed 
to by buf. Readv performs the same action, but scatters the input data into the iovcnt buffers specified by 
the members of the iovec array: iov[0], iov[l], iov[iovcnt- 1]. 

For readv, the iovec structure is defined as 

struct iovec { 

caddr t iov base; 
int iovlen; 

}; 

Each iovec entry specifies the base address and length of an area in memory where data should be placed. 
Readv will always fill an area completely before proceeding to the next. 

On objects capable of seeking, the read starts at a position given by the pointer associated with d, see 
lseek( 2). Upon return from read, the pointer is incremented by the number of bytes actually read. 

Objects that are not capable of seeking always read from the current position. The value of the pointer 
associated with such a object is undefined. 

Upon successful completion, read and readv return the number of bytes actually read and placed in the 
buffer. The system guarantees to read the number of bytes requested if the descriptor references a file 
which has that many bytes left before the end-of-file, but in no other cases. 

If the returned value is 0, then end-of-file has been reached. 

RETURN VALUE 

If successful, the number of bytes actually read is returned. Otherwise, a -1 is returned and the global vari- 
able errno is set to indicate the error. 

ERRORS 

Read and readv will fail if one or more of the following are true: 

[EBADF] Fildes is not a valid file descriptor open for reading. 

[EFAULT] Buf points outside the allocated address space. 

[EINTR] A read from a slow device was interrupted before any data arrived by the delivery of a 

signal. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

In addition, readv may return one of the following errors: 

[EINVAL] Iovcnt was less than or equal to 0, or greater than 16. 

[EINVAL] One of the iov Jen values in the iov array was negative. 
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[EINVAL] The sum of the iov_len values in the iov array overflowed a 32-bit integer. 
[EFAULT] Part of iov points outside the process’s allocated address space. 

SEE ALSO 

dup(2), open(2), pipe(2), socket(2), socketpair(2) 
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NAME 

readlink - read value of a symbolic link 
SYNOPSIS 

cc = readlink(path, buf, bufsiz) 
nut cc; 

char *path, *buf; 
int bufsiz; 

DESCRIPTION 

Readlink places the contents of the symbolic link name in the buffer buf which has size bufsiz. The con- 
tents of the link are not null terminated when returned. 

RETURN VALUE 

The call returns the count of characters placed in the buffer if it succeeds, or a -1 if an error occurs, placing 
the error code in the global variable errno. 

ERRORS 

Readlink will fail and the file mode will be unchanged if: 

[EPERM] The path argument contained a byte with the high-order bit set. 

[ENAMETOOLONG] 

The pathname was too long. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[ENXIO] The named file is not a symbolic link. 

[EACCES] Search permission is denied on a component of the path prefix. 

[EINVAL] The named file is not a symbolic link. 

[EFAULT] Buf extends outside the process’s allocated address space. 

[ELOOP] Too many symbolic links were encountered in translating the pathname. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

SEE ALSO 

stat(2), lstat(2), symlink(2) 
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NAME 

reboot - reboot system or halt processor 
SYNOPSIS 

#include <sys/reboot.h> 

reboot(howto) 
int howto; 

DESCRIPTION 

Reboot reboots the system, and is invoked automatically in the event of unrecoverable system failures. 
Howto is a mask of options passed to the bootstrap program. The system call interface permits only 
RBHALT or RBAUTOBOOT to be passed to the reboot program; the other flags are used in scripts 
stored on the console storage media, or used in manual bootstrap procedures. When none of these options 
(e.g. RB AUTOBOOT) is given, the system is rebooted from file “vmunix” in the root file system of unit 
0 of a disk chosen in a processor specific way. An automatic consistency check of the disks is then nor- 
mally performed. 

The bits of howto are: 

RBHALT 

the processor is simply halted; no reboot takes place. RB HALT should be used with caution. 
RBASKNAME 

Interpreted by the bootstrap program itself, causing it to inquire as to what file should be booted. 
Normally, the system is booted from the file “vmunix” without asking. 

RBSINGLE 

Normally, the reboot procedure involves an automatic disk consistency check and then multi-user 
operations. RB SINGLE prevents the consistency check, rather simply booting the system with a 
single-user shell on the console. RB SINGLE is interpreted by the init(Z) program in the newly 
booted system. 

Only the super-user may reboot a machine. 

RETURN VALUES 

If successful, this call never returns. Otherwise, a -1 is returned and an error is returned in the global vari- 
able errno . 

ERRORS 

[EPERM] The caller is not the super-user. 

SEE ALSO 

crash(8S), halt(8), init(8), reboot(8) 
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NAME 

recv, recvfrom, recvmsg - receive a message from a socket 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

cc = recv(s, buf, len, flags) 
int cc, s; 
char *buf; 
int len, flags; 

cc = recvfrom(s, buf, len, flags, from, fromlen) 

int cc, s; 

char *buf; 

int len, flags; 

struct sockaddr *from; 

int *fromlen; 

cc = recvmsg(s, msg, flags) 
int cc, s; 

struct msghdr msg[]; 
int flags; 

DESCRIPTION 

Recv, recvfrom, and recvmsg are used to receive messages from a socket. 

The recv call may be used only on a connected socket (see connect (2)), while recvfrom and recvmsg may 
be used to receive data on a socket whether it is in a connected state or not 

If from is non-zero, the source address of the message is filled in. Fromlen is a value-result parameter, ini- 
tialized to the size of the buffer associated with from, and modified on return to indicate the actual size of 
the address stored there. The length of the message is returned in cc. If a message is too long to fit in the 
supplied buffer, excess bytes may be discarded depending on the type of socket the message is received 
from; see socket (2). 

If no messages are available at the socket, the receive call waits for a message to arrive, unless the socket is 
nonblocking (see ioctl{ 2)) in which case a cc of -1 is returned with the external variable ermo set to 
EWOULDBLOCK. 

The select^ 2) call may be used to determine when more data arrives. 

Th e flags argument to a send call is formed by or’ ing one or more of the values, 

#define MSG_PEEK Oxl /* peek at incoming message */ 

#define MSG_OOB 0x2 /* process out-of-band data */ 

The recvmsg call uses a msghdr structure to minimize the number of directly supplied parameters. This 
structure has the following form, as defined in <sysl socket. h > : 

struct msghdr { 


caddrt 

msgjiame; 

/* optional address */ 

int 

msgjiamelen; 

/* size of address */ 

struct 

iovec * msgjov; 

/* scatter/gather array */ 

int 

msgiovlen; 

/* # elements in msg iov */ 

caddrt 

msg_accrights; 

/* access rights sent/received */ 

int 

msgaccrightslen; 



}; 

Here msgjiame and msgjiamelen specify the destination address if the socket is unconnected; msgjiame 
may be given as a null pointer if no names are desired or required. The msgjov and msg_iovlen describe 
the scatter gather locations, as described in read{ 2). Access rights to be sent along with the message are 
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specified in msg_accrights, which has length msg_accrightslen. 

RETURN VALUE 

These calls return the number of bytes received, or -1 if an error occurred. 

ERRORS 

The calls fail if: 

[EBADF] The argument s is an invalid descriptor. 

[ENOTSOCK] The argument s is not a socket. 

[EWOULDBLOCK] The socket is marked non-blocking and the receive operation would block. 

[EINTR] The receive was interrupted by delivery of a signal before any data was available 

for the receive. 

[EFAULT] The data was specified to be received into a non-existent or protected part of the 

process address space. 

SEE ALSO 

read(2), send(2), socket(2) 
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NAME 

rename - change the name of a file 

SYNOPSIS 

rename(from, to) 
char *from, *to; 

DESCRIPTION 

Rename renames the link named from as to. If to exists, then it is first removed. Both from and to must be 
of the same type (that is, both directories or both non-directories), and must reside on the same file system. 

Rename guarantees that an instance of to will always exist, even if the system should crash in the middle of 
the operation. 

CAVEAT 

The system can deadlock if a loop in the file system graph is present This loop takes the form of an entry 
in directory “a”, say “a/foo”, being a hard link to directory “b”, and an entry in directory “b”, say 
b/bar ’, being a hard link to directory “a”. When such a loop exists and two separate processes attempt 
to perform “rename a/foo b/bar” and “rename b/bar a/foo”, respectively, the system may deadlock 
attempting to lock both directories for modification. Hard links to directories should be replaced by sym- 
bolic links by the system administrator. 

RETURN VALUE 

A 0 value is returned if the operation succeeds, otherwise rename returns -1 and the global variable errno 
indicates the reason for the failure. 

ERRORS 

Rename will fail and neither of the argument files will be affected if any of the following are true: 
[ENOTDIR] A component of either path prefix is not a directory. 

[ENOENT] A component of either path prefix does not exist. 

[EACCES] A component of either path prefix denies search permission. 

[ENOENT] The file named by from does not exist. 

[EXDEV] The link named by to and the file named by from are on different logical devices (file 

systems). 

[EACCES] The requested rename requires writing in a directory with a mode that denies write per- 
mission. 

[EROFS] The requested rename requires writing in a directory on a read-only file system. 

[EFAULT] Either or both of from or to point outside the process’s allocated address space. 

[EINVAL] From is a parent directory of to . 

[ENAMETOOLONG] 

The pathname was too long. 

[ENOSPC] The directory in which the entry for the new name is being placed cannot be extended 
because there is no space left on the file system containing the directory. 

[EDQUOT] The directory in which the entry for the new name is being placed cannot be extended 
because the user’s quota of disk blocks on the file system containing the directory has 
been exhausted. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

[EPERM] One of the two pathnames contains a character with the high-order bit set (that is to say, 

a non-ASCII character.) 

[ENOTEMPTY] The directory to is not empty. 

[ELOOP] Too many symbolic links were encountered while translating one of the pathnames. 
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[EBUSY] to exists, is a directory, and is the mountpoint for a mounted file system. 

SEE ALSO 

open(2) 
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NAME 

rmdir - remove a directory file 

SYNOPSIS 

rmdir(path) 
char *path; 

DESCRIPTION 

Rmdir removes a directory file whose name is given by path. The directory must not have any entries other 
than and 

RETURN VALUE 

A 0 is returned if the remove succeeds; otherwise a -1 is returned and an error code is stored in the global 
location errno . 

ERRORS 

The named file is removed unless one or more of the following are true: 

[ENOTEMPTY] The named directory contains files other than and in it. 

[EPERM] The pathname contains a character with the high-order bit set. 

[ENAMETOOLONG] 

The pathname was too long. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCES] A component of the path prefix denies search permission. 

[EACCES] Write permission is denied on the directory containing the link to be removed. 

[EBUSY] The directory to be removed is the mount point for a mounted file system. 

[EROFS] The directory entry to be removed resides on a read-only file system. 

[EFAULT] Path points outside the process’s allocated address space. 

[ELOOP] Too many symbolic links were encountered in translating the pathname. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

SEE ALSO 

mkdir(2), unlink(2) 


88 


Last change: 19 August 1985 


Sun Release 3.0 



SELECT ( 2 ) 


SYSTEM CALLS 


SELECT (2) 


NAME 

select - synchronous I/O multiplexing 
SYNOPSIS 

#include <sys/time.h> 

nfds = select(width, readfds, writefds, execptfds, timeout) 
int width, *readfds, *writefds, *execptfds; 
struct timeval ^timeout; 

DESCRIPTION 

Select examines the I/O descriptors specified by the bit masks readfds, writefds, and execptfds to see if 
they are ready for reading, writing, or have an exceptional condition pending, respectively. Width is the 
number of significant bits in each bit mask that represent a file descriptor. Typically width has the value 
returned by getdtablesize(2) for the maximum number of file descriptors or is the constant 32 (number of 
bits in an int). File descriptor /is represented by the bit “l«f ’ in the mask. Select returns, in place, a 
mask of those descriptors which are ready. The total number of ready descriptors is returned in nfds. 

If timeout is a non-zero pointer, it specifies a maximum interval to wait for the selection to complete. If 
timeout is a zero pointer, the select blocks indefinitely. To effect a poll, the timeout argument should be 
non-zero, pointing to a zero valued timeval structure. 

Any of readfds, writefds, and execptfds may be given as 0 if no descriptors are of interest 
RETURN VALUE 

Select returns the number of descriptors which are contained in the bit masks, or -1 if an error occurred. If 
the time limit expires then select returns 0. 

ERRORS 

An error return from select indicates: 

[EBADF] One of the bit masks specified an invalid descriptor. 

[EINTR] A signal was delivered before any of the selected events occurred or the time limit 

expired. 

SEE ALSO 

accept(2), connect(2), gettimeofday(2), read(2), write(2), recv(2), send(2), getdtablesize(2) 

BUGS 

The descriptor masks are always modified on return, even if the call returns as the result of the timeout. 
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NAME 

send, sendto, sendmsg - send a message from a socket 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

cc = send(s, msg, len, flags) 
int cc, s; 
char *msg; 
int len, flags; 

cc = sendto(s, msg, len, flags, to, tolen) 

int cc, s; 

char *msg; 

int len, flags; 

struct sockaddr *to; 

int tolen; 

cc = sendmsg(s, msg, flags) 
int cc, s; 

struct msghdr msg[]; 
int flags; 

DESCRIPTION 

S is a socket created with socket (2). Send, sendto, and sendmsg are used to transmit a message to another 
socket. Send may be used only when the socket is in a connected state, while sendto and sendmsg may be 
used at any time. 

The address of the target is given by to with tolen specifying its size. The length of the message is given by 
len. If the message is too long to pass atomically through the underlying protocol, then the error 
EMSGSIZE is returned, and the message is not transmitted. 

No indication of failure to deliver is implicit in a send. Return values of -1 indicate some locally detected 
errors. 


If no messages space is available at the socket to hold the message to be transmitted, then send normally 
blocks, unless the socket has been placed in non-blocking i/o mode. The select{ 2) call may be used to 
determine when it is possible to send more data. 

The flags parameter may be set to SOF OOB to send “out-of-band” data on sockets which support this 
notion (e.g. SOCK STREAM). 

See recv(2) for a description of the msghdr structure. 


RETURN VALUE 

The call returns the number of characters sent, or -1 if an error occurred. 


ERRORS 

[EBADF] 

[ENOTSOCK] 

DEFAULT] 

DEMSGSIZE] 

[EW OULDBLOCK] 

SEE ALSO 

recv(2), socket(2) 


An invalid descriptor was specified. 

The argument s is not a socket 

An invalid user space address was specified for a parameter. 

The socket requires that message be sent atomically, and the size of the message 
to be sent made this impossible. 

The socket is marked non-blocking and the requested operation would block. 
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NAME 

setgroups - set group access list 
SYNOPSIS 

#include <sys/param.h> 

setgroups(ngroups, gidset) 
int ngroups, *gidset; 

DESCRIPTION 

Setgroups sets the group access list of the current user process according to the array gidset. The parame- 
ter ngroups indicates the number of entries in the array and must be no more than NGRPS, as defined in 
<sys/param.h>. 

Only the super-user may set new groups. 

RETURN VALUE 

A 0 value is returned on success, -1 on error, with a error code stored in err no. 

ERRORS 

The setgroups call will fail if: 

[EPERM] The caller is not the super-user. 

DEFAULT] The address specified for gidset is outside the process address space. 

SEE ALSO 

getgroups(2), initgroups(3) 
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NAME 

setpgrp - set process group 

SYNOPSIS 

setpgrp(pid, pgrp) 
int pid, pgrp; 

DESCRIPTION 

Setpgrp sets the process group of the specified process pid to the specified pgrp. If pid is zero, then the call 
applies to the current process. 

If the invoker is not the super-user, then the affected process must have the same effective user-id as the 
invoker or be a descendant of the invoking process. 

RETURN VALUE 

Setpgrp returns when the operation was successful. If the request failed, -1 is returned and the global vari- 
able errno indicates the reason. 

ERRORS 

Setpgrp will fail and the process group will not be altered if one of the following occur: 

[ESRCH] The requested process does not exist. 

[EPERM] The effective user ID of the requested process is different from that of the caller and the 

process is not a descendent of the calling process. 

SEE ALSO 

getpgrp(2) 
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NAME 

setquota - enable/disable quotas on a file system 
SYNOPSIS 

setquota(special, file) 
char ^special, *file; 

DESCRIPTION 

Disc quotas are enabled or disabled with the setquota call. Special indicates a block special device on 
which a mounted file system exists. If file is nonzero, it specifies a file in that file system from which to 
take the quotas. If file is 0, then quotas are disabled on the file system. The quota file must exist; it is nor- 
mally created with the quotacheck{ 8) program. 

Only the super-user may turn quotas on or off. 

SEE ALSO 

quota(2), quotacheck(8), quotaon(8) 

RETURN VALUE 

A 0 return value indicates a successful call. A value of -1 is returned when an error occurs and errno is set 
to indicate the reason for failure. 

ERRORS 

Setquota will fail when one of the following occurs: 

[EPERM] The caller is not the super-user. 

[ENOENT] Special does not exist 
[ENOTBLK] Special is not a block device. 

[ENXIO] The major device number of special is out of range (this indicates no device driver exists 

for the associated hardware). 

[EPERM] The pathname contains a character with the high-order bit set 

[ENOTDIR] A component of the path prefix in file is not a directory. 

[EACCES] File resides on a file system different from special . 

[EACCES] File is not a plain file. 

[ENAMETOOLONG] 

The pathname was too long. 

[EFAULT] Special or file points outside the process’s allocated address space. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

BUGS 

The error codes are in a state of disarray; too many errors appear to the caller as one value. 
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NAME 

setregid - set real and effective group ED 

SYNOPSIS 

setregid(rgid, egid) 
int rgid, egid; 

DESCRIPTION 

The real and effective group ID’s of the cun-ent process are set to the arguments. Only the super-user may 
change the real group ID of a process. Unpriviledged users may change the effective group ED to the real 
group ID, but to no other. 

Supplying a value of-1 for either the real or effective group ED forces the system to substitute the current 
ID in place of the -1 parameter. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of-1 is returned and errno is set 
to indicate the error. 

ERRORS 

[EPERM] The current process is not the super-user and a change other than changing the effective 

group-id to the real group-id was specified. 

SEE ALSO 

getgid(2), setreuid(2), setgid(3C) 
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NAME 

setreuid - set real and effective user ID’s 

SYNOPSIS 

setreuid (ruid, euid) 
int ruid, euid; 

DESCRIPTION 

The real and effective user ID’s of the current process are set according to the arguments. If ruid or euid is 
-1, the current uid is filled in by the system. Only the super-user may modify the real uid of a process. 
Users other than the super-user may change the effective uid of a process only to the real uid. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set 
to indicate the error. 

ERRORS 

[EPERM] The current process is not the super-user and a change other than changing the effective 

user-id to the real user-id was specified. 

SEE ALSO 

getuid(2), setregid(2), setuid(3) 
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NAME 

shutdown - shut down part of a full-duplex connection 

SYNOPSIS 

shutdowns, how) 
int s, how; 

DESCRIPTION 

The shutdown call causes all or part of a full-duplex connection on the socket associated with s to be shut 
down. If how is 0, then further receives will be disallowed. If how is 1, then further sends will be disal- 
lowed. If how is 2, then further sends and receives will be disallowed. 

DIAGNOSTICS 

A 0 is returned if the call succeeds, -1 if it fails. 

ERRORS 

The call succeeds unless: 

[EBADF] S is not a valid descriptor. 

[ENOTSOCK] S is a file, not a socket. 

[ENOTCONN] The specified socket is not connected. 

SEE ALSO 

connect(2), socket(2) 

BUGS 

The how values should be defined constants. 
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NAME 

sigblock - block signals 
SYNOPSIS 

oldmask = sigblock(mask); 
int mask; 

DESCRIPTION 

Sigblock adds the signals specified in mask to the set of signals currently being blocked from delivery. Sig- 
nal i is blocked if the i-l’th bit in mask is a 1. That is, to block SIGINT use sigblock((l«(SIGINT-l)). 
The previous mask is returned, and may be restored using sigsetmask(2). 

It is not possible to block SIGKILL, SIGSTOP, or SIGCONT; this restriction is silently imposed by the 
system. 

RETURN VALUE 

The previous set of masked signals is returned. 

SEE ALSO 

kill(2), sigvec(2), sigsetmask(2), signal(3) 
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NAME 

sigpause - atomically release blocked signals and wait for interrupt 
SYNOPSIS 

sigpause(sigmask) 
int sigmask; 

DESCRIPTION 

Sigpause assigns sigmask to the set of masked signals and then waits for a signal to arrive; on return the set 
of masked signals is restored. Sigmask is usually 0 to indicate that no signals are now to be blocked. Sig- 
pause always terminates by being interrupted, returning EINTR. 

In normal usage, a signal is blocked using sigblock{ 2), to begin a critical section, variables modified on the 
occurance of the signal are examined to determine that there is no work to be done, and the process pauses 
awaiting work by using sigpause with the mask returned by sigblock. 

SEE ALSO 

sigblock(2), sigvec(2), signal(3) 


98 


Last change: 20 August 1985 


Sun Release 3.0 



SIGSETMASK ( 2 ) 


SYSTEM CALLS 


SIGSETMASK (2) 


NAME 

sigsetmask - set current signal mask 

SYNOPSIS 

sigsetmask(mask); 
int mask; 

DESCRIPTION 

Sigsetmask sets the current signal mask (those signals which are blocked from delivery). Signal i is 
blocked if the i-l’th bit in mask is a 1. 

The system quietly disallows SIGKILL, SIGSTOP, or SIGCONT to be blocked. 

RETURN VALUE 

The previous set of masked signals is returned. 

SEE ALSO 

kill(2), sigvec(2), sigblock(2), sigpause(2), signal(3) 
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NAME 

sigstack - set and/or get signal stack context 
SYNOPSIS 

#include <signal.h> 

struct sigstack { 

caddrt ss_sp; 
int ss_onstack; 

}; 

sigstack(ss, oss) 
struct sigstack *ss, *oss; 

DESCRIPTION 

Sigstack allows users to define an alternate stack on which signals are to be processed. If ss is non-zero, it 
specifies a signal stack on which to deliver signals and tells the system if the process is currently executing 
on that stack. When a signal’s action indicates its handler should execute on the signal stack (specified 
with a sigvec(2) call), the system checks to see if the process is currently executing on that stack. If the 
process is not currently executing on the signal stack, the system arranges a switch to the signal stack for 
the duration of the signal handler’s execution. If oss is non-zero, the current signal stack state is returned. 

NOTES 

Signal stacks are not “grown” automatically, as is done for the normal stack. If the stack overflows 
unpredictable results may occur. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set 
to indicate the error. 

ERRORS 

Sigstack will fail and the signal stack context will remain unchanged if one of the following occurs. 
[EFAULT] Either ss or oss points to memory which is not a valid part of the process address space. 
SEE ALSO 

sigvec(2), setjmp(3), signal(3) 
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NAME 

sigvec - software signal facilities 

SYNOPSIS 

#include <signal.h> 

struct sigvec { 

int (*sv_handler)(); 

int sv_ma.sk; 

int svonstack; 

}; 

sigvec(sig, vec, ovec) 
int sig; 

struct sigvec *vec, *ovec; 

DESCRIPTION 

The system defines a set of signals that may be delivered to a process. Signal delivery resembles the 
occurrence of a hardware interrupt: the signal is blocked from further occurrence, the current process con- 
text is saved, and a new one is built. A process may specify a handler to which a signal is delivered, or 
specify that a signal is to be blocked or ignored. A process may also specify that a default action is to be 
taken by the system when a signal occurs. Normally, signal handlers execute on the current stack of the 
process. This may be changed, on a per-handler basis, so that signals are taken on a special signal stack. 

All signals have the same priority. Signal routines execute with the signal that caused their invocation 
blocked, but other signals may yet occur. A global signal mask defines the set of signals currently blocked 
from delivery to a process. The signal mask for a process is initialized from that of its parent (normally 0). 
It may be changed with a sigblock{ 2) or sigsetmask{ 2) call, or when a signal is delivered to the process. 

When a signal condition arises for a process, the signal is added to a set of signals pending for the process. 
If the signal is not currently blocked by the process then it is delivered to the process. When a signal is 
delivered, the current state of the process is saved, a new signal mask is calculated (as described below), 
and the signal handler is invoked. The call to the handler is arranged so that if the signal handling routine 
returns normally the process will resume execution in the context from before the signal’s delivery. If the 
process wishes to resume in a different context, then it must arrange to restore the previous context itself. 

When a signal is delivered to a process a new signal mask is installed for the duration of the process’ signal 
handler (or until a sigblock or sigsetmask call is made). This mask is formed by taking the current signal 
mask, adding the signal to be delivered, and or’ing in the signal mask associated with the handler to be 
invoked. 

Sigvec assigns a handler for a specific signal. If vec is non-zero, it specifies a handler routine and mask to 
be used when delivering the specified signal. Further, if sv_onstack is 1, the system will deliver the signal 
to the process on a signal stack, specified with sigstack(2). If ovec is non-zero, the previous handling 
information for the signal is returned to the user. 

The mask specified in vec is not allowed to block SIGKILL, SIGSTOP, or SIGCONT. The system 
enforces this restriction silently. 

The following is a list of all signals with names as in the include file <signal.h>: 


SIGHUP 

1 

hangup 

SIGINT 

2 

interrupt 

SIGQUIT 

3* 

quit 

SIGILL 

4* 

illegal instruction (other than A-line or F-line op code) 

SIGTRAP 

5* 

trace trap 

SIGIOT 

6* 

IOT instruction (not generated on Suns) 

SIGEMT 

7* 

EMT instruction (A-line or F-line op code) 

SIGFPE 

8* 

floating point exception 

SIGKILL 

9 

kill (cannot be caught, blocked, or ignored) 
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NOTES 


CODES 


SIGBUS 

10* 

SIGSEGV 

11* 

SIGSYS 

12* 

SIGPIPE 

13 

SIGALRM 

14 

SIGTERM 

15 

SIGURG 

16 

SIGSTOP 

17t 

SIGTSTP 

18t 

SIGCONT 

19* 

SIGCHLD 

20* 

SIGTTIN 

21t 

SIGTTOU 

22t 

SIGIO 

23 

SIGXCPU 

24 

SIGXFSZ 

25 

SIGVTALRM 26 

SIGPROF 

27 

SIGWINCH 

28* 


bus error 

segmentation violation 
bad argument to system call 
write on a pipe with no one to read it 
alarm clock 

software termination signal 
urgent condition present on socket 
stop (cannot be caught, blocked, or ignored) 
stop signal generated from keyboard 
continue after stop (cannot be blocked) 
child status has changed 

background read attempted from control terminal 
background write attempted to control terminal 
i/o is possible on a descriptor (see fcntl(2)) 
cpu time limit exceeded (see setrlimit( 2)) 
file size limit exceeded (see setrlimit(2 )) 
virtual time alarm (see setitimer( 2)) 
profiling timer alarm (see setitimer(2)) 
window changed (see win (4S)) 


The starred signals in the list above cause a core image if not caught or ignored. 

Once a signal handler is installed, it remains installed until another sigvec call is made, or an execve(2) is 
performed. The default action for a signal may be reinstated by setting svhandler to SIGDFL; this 
default is termination (with a core image for starred signals) except for signals marked with • or t. Signals 
marked with • are discarded if the action is SIG DFL; signals marked with t cause the process to stop. If 
sv handler is SIG_IGN the signal is subsequently ignored, and pending instances of the signal are dis- 
carded. 


If a caught signal occurs during certain system calls, causing the call to terminate prematurely, the call is 
automatically restarted. In particular this can occur during a read or write (2) on a slow device (such as a 
terminal; but not a file) and during a wait {2). 

After afork(2) or vfork( 2) the child inherits all signals, the signal mask, and the signal stack. 

The execve (2) call resets all caught signals to default action; ignored signals remain ignored; the signal 
mask remains the same; the signal stack state is reset. 


The handler routine can be declared: 

handler(sig, code, scp) 
int sig, code; 
struct sigcontext *scp; 

Here sig is the signal number. Code is a parameter of certain signals that provides additional detail. Scp is 
a pointer to the sigcontext structure (defined in <signal.h>), used to restore the context from before the sig- 
nal. 

Programs that must be portable to UNIX systems other than 4.2 BSD should use the signalQ) interface 
instead. 


The following defines the codes for signals which produce them. All of these symbols are defined in 
<signal.h > : 

Hardware condition Signal Code 


Illegal instruction 
Privilege violation 


SIGILL ILL_INSTR_FAULT 

SIGILL ILL_PRIVVIO_FAULT 
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Coprocessor protocol error SIGILL ILL_INSTR_FAULT 

Trap #n (1 <= n <= 14) SIGILL ILL_TRAPn_FAULT 

n’s above should be italicized 

A-line op code SIGEMT EMT_EMU1010 

F-line op code SIGEMT EMT_EMU 1111 

Integer division by zero SIGFPE FPE INTDIV TRAP 

CHK or CHK2 instruction SIGFPE FPECHKINSTTRAP 

TRAPV or TRAPcc or cpTRAPcc SIGFPE FPE TRAPV TRAP 

IEEE floating point compare unordered SIGFPE FPEFLTBSUNTRAP 
IEEE floating point inexact SIGFPE FPE FLTINEX TRAP 

IEEE floating point division by zero SIGFPE FPE FLTDIV TRAP 

IEEE floating point underflow SIGFPE FPE_FLTUND_TRAP 

IEEE floating point operand error SIGFPE FPE FLTOPERR TRAP 
IEEE floating point overflow SIGFPE FPE FLTOVF FAULT 

IEEE floating point signaling NaN SIGFPE FPE FLTN AN_TR AP 

RETURN VALUE 

A 0 value indicated that the call succeeded. A -1 return value indicates an error occurred and errno is set 
to indicate the reason. 

ERRORS 

Sigvec will fail and no new signal handler will be installed if one of the following occurs: 

[EFAULT] Either vec or ovec points to memory which is not a valid part of the process address 
space. 

[EINV AL] Sig is not a valid signal number. 

[EINVAL] An attempt is made to ignore or supply a handler for SIGKILL or SIGSTOP. 

[EINVAL] An attempt is made to ignore SIGCONT (by default SIGCONT is ignored). 

SEE ALSO 

kill(l), ptrace(2), kill(2), sigblock(2), sigsetmask(2), sigpause(2) sigstack(2), sigvec(2), setjmp(3), sig- 
nal(3), tty(4) 
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NAME 

socket - create an endpoint for communication 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

s = socket(af, type, protocol) 
int s, af, type, protocol; 

DESCRIPTION 

Socket creates an endpoint for communication and returns a descriptor. 

The af parameter specifies an address format with which addresses specified in later operations using the 
socket should be interpreted. These formats are defined in the include file <srysl socket. h> . The currently 
understood formats are 

AF UNIX (UNIX path names), 

AF INET (ARPA Internet addresses), 

AFPUP (Xerox PUP-I Internet addresses), and 

AF IMPLINK (IMP “host at IMP’ ’ addresses). 

The socket has the indicated type which specifies the semantics of communication. Currently defined types 
are: 

SOCKSTREAM 

SOCKDGRAM 

SOCK_RAW 

SOCKSEQPACKET 

SOCKRDM 

A SOCK STREAM type provides sequenced, reliable, two-way connection based byte streams with an 
out-of-band data transmission mechanism. A SOCK_DGRAM socket supports datagrams (connectionless, 
unreliable messages of a fixed (typically small) maximum length). SOCK RAW sockets provide access to 
internal network interfaces. The types SOCK_RAW, which is available only to the super-user, and 
SOCK SEQPACKET and SOCK RDM, which are planned, but not yet implemented, are not described 
here. 

The protocol specifies a particular protocol to be used with the socket. Normally only a single protocol 
exists to support a particular socket type using a given address format. However, it is possible that many 
protocols may exist in which case a particular protocol must be specified in this manner. The protocol 
number to use is particular to the “communication domain” in which communication is to take place; see 
services (5) and protocols^ 5). 

Sockets of type SOCK STREAM are full-duplex byte streams, similar to pipes. A stream socket must be 
in a connected state before any data may be sent or received on it. A connection to another socket is 
created with a connect (2) call. Once connected, data may be transferred using read (2) and write (2) calls 
or some variant of the send{ 2) and recv(2) calls. When a session has been completed a close( 2) may be 
performed. Out-of-band data may also be transmitted as described in send (2) and received as described in 
recv(2). 

The communications protocols used to implement a SOCK_STREAM insure that data is not lost or dupli- 
cated. If a piece of data for which the peer protocol has buffer space cannot be successfully transmitted 
within a reasonable length of time, then the connection is considered broken and calls will indicate an error 
with -1 returns and with ETIMEDOUT as the specific code in the global variable ermo. The protocols 
optionally keep sockets “warm” by forcing transmissions roughly every minute in the absence of other 
activity. An error is then indicated if no response can be elicited on an otherwise idle connection for a 
extended period (e.g. 5 minutes). A SIGPIPE signal is raised if a process sends on a broken stream; this 
causes naive processes, which do not handle the signal, to exit. 
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SOCKDGRAM and SOCK RAW sockets allow sending of datagrams to correspondents named in 
send (2) calls. It is also possible to receive datagrams at such a socket with recv( 2). 

An fcntl (2) call can be used to specify a process group to receive a SIGURG signal when the out-of-band 
data arrives. 


The operation of sockets is controlled by socket level options. These options are defined in the file 
<sys/ socket. h> and explained below. Setsockopt and getsockopt( 2) are used to set and get options, respec- 
tively. 


SODEBUG 

SOREUSEADDR 

SOKEEP ALIVE 

SODONTROUTE 

SOLINGER 

SOJDONTLINGER 


turn on recording of debugging information 

allow local address reuse 

keep connections alive 

do no apply routing on outgoing messages 

linger on close if data present 

do not linger on close 


SO DEBUG enables debugging in the underlying protocol modules. SO REUSEADDR indicates the 
rules used in validating addresses supplied in a bind(2) call should allow reuse of local addresses. 
SO KEEPALIVE enables the periodic transmission of messages on a connected socket. Should the con- 
nected party fail to respond to these messages, the connection is considered broken and processes using the 
socket are notified via a SIGPIPE signal. SO DONTROUTE indicates that outgoing messages should 
bypass the standard routing facilities. Instead, messages are directed to the appropriate network interface 
according to the network portion of the destination address. SOLINGER and SO DONTLINGER control 
the actions taken when unsent messags are queued on socket and a close ( 2) is performed. If the socket 
promises reliable delivery of data and SO LINGER is set, the system will block the process on the close 
attempt until it is able to transmit the data or until it decides it is unable to deliver the information (a 
timeout period, termed the linger interval, is specified in the setsockopt call when SO LINGER is 
requested). If SO_DONTLINGER is specified and a close is issued, the system will process the close in a 
manner which allows the process to continue as quickly as possible. 


RETURN VALUE 

A -1 is returned if an error occurs, otherwise the return value is a descriptor referencing the socket. 


ERRORS 

The socket call fails if: 


[EAFNOSUPPORT] The specified address family is not supported in this version of the system. 
[ESOCKTNOSUPPORT] 

The specified socket type is not supported in this address family. 

[EPROTONOSUPPORT] 

The specified protocol is not supported. 

[EMFILE] The per-process descriptor table is full. 

[ENOBUFS] No buffer space is available. The socket cannot be created. 

SEE ALSO 

accept(2), bind(2), connect(2), getsockname(2), getsockopt(2), ioctl(2), listen(2), recv(2), select(2), 
send(2), shutdown(2), socketpair(2) 

“A 4.2BSD Interprocess Communication Primer”. 

BUGS 

The use of keepalives is a questionable feature for this layer. 
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NAME 

socketpair - create a pair of connected sockets 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

socketpair(d, type, protocol, sv) 
int d, type, protocol; 
int sv[2]; 

DESCRIPTION 

The socketpair system call creates an unnamed pair of connected sockets in the specified domain d, of the 
specified type and using the optionally specified protocol. The descriptors used in referencing the new 
sockets are returned in w[0] and jv[1]. The two sockets are indistinguishable. 

DIAGNOSTICS 

A 0 is returned if the call succeeds, -1 if it fails. 

ERRORS 

The call succeeds unless: 

[EMFILE] Too many descriptors are in use by this process. 

[EAFNOSUPPORT] The specified address family is not supported on this machine. 

[EPROTONOSUPPORT] 

The specified protocol is not supported on this machine. 

[EOPNOSUPPORT] The specified protocol does not support creation of socket pairs. 

[EFAULT] The address sv does not specify a valid part of the process address space. 

SEE ALSO 

read(2), write(2), pipe(2) 

BUGS 

This call is currently implemented only for the UNIX domain. 
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NAME 

stat, lstat, fstat - get file status 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/stat.h> 

stat(path, buf) 
char *path; 
struct stat *buf; 

Istat(path, buf) 
char *path; 
struct stat *buf; 

fstat(fd, buf) 
int fd; 

struct stat *buf; 

DESCRIPTION 

Stat obtains information about the file path. Read, write or execute permission of the named file is not 
required, but all directories listed in the path name leading to the file must be reachable. 

Lstat is like stat except in the case where the named file is a symbolic link, in which case lstat returns infor- 
mation about the link, while stat returns information about the file the link references. 

Fstat obtains the same information about an open file referenced by the argument descriptor, such as would 
be obtained by an open call. 

Buf is a pointer to a stat structure into which information is placed concerning the file. The contents of the 
structure pointed to by buf contains the following members: 


devt 

stdev; 

/* device inode resides on *1 

inot 

stino; 

1* this inode’s number */ 

u_short 

stjmode; 

1* protection */ 

short 

stnlink; 

/* number or hard links to the file */ 

short 

stuid; 

1* user-id of owner */ 

short 

stgid; 

1* group-id of owner */ 

devt 

st_rdev; 

1* the device type, for inode that is device */ 

offt 

st_size; 

/* total size of file */ 

time_t 

st_atime; 

/* file last access time *1 

time_t 

st_mtime; 

I* file last modify time */ 

timet 

stctime; 

1* file last status change time */ 

long 

st_blksize; 

1* optimal blocksize for file system i/o ops */ 

long 

stblocks; 

/* actual number of blocks allocated */ 


statime Time when file data was last read or modified. Changed by the following system calls: 

mknod( 2), utimes(2), read (2), write (2), and truncate (2). For reasons of efficiency, st atime 
is not set when a directory is searched, although this would be more logical. 

st_mtime Time when data was last modified. It is not set by changes of owner, group, link count, or 
mode. Changed by the following system calls: mknod{ 2), utimes(2), write (2). 

stctime Time when file status was last changed. It is set both both by writing and changing the i- 
node. Changed by the following system calls: chmod(2 ) chown{2), link(2), mknod(2), 
unlink(2), utimes(2), write(2), truncate (2). 

The status information word stjnode has bits: 

#define S_IFMT 0170000 /* type of file */ 

#define S_IFDIR 0040000 I* directory */ 

#define S_IFCHR 0020000 /* character special */ 
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#define S IFBLK 

0060000 

/* block special */ 

#define S IFREG 

0100000 

/* regular */ 

#define S IFLNK 

0120000 

/* symbolic link */ 

tdefine S IFSOCK 

0140000 

/* socket */ 

#define S ISUID 

0004000 

/* set user id on execution *1 

#define S ISGID 

0002000 

/* set group id on execution */ 

#define S_ISVTX 

0001000 

/* save swapped text even after use */ 

#define S IRE AD 

0000400 

1* read permission, owner */ 

#defineS IWRITE 

0000200 

/* write permission, owner */ 

#define SJEXEC 

0000100 

/* execute/search permission, owner */ 


The mode bits 0000070 and 0000007 encode group and others permissions (see chmod(2)). 

When fd is associated with a pipe, fstat reports an ordinary file with an i-node number, restricted permis- 
sions, and a not necessarily meaningful length. 

RETURN VALUE 

Upon successful completion a value of 0 is returned. Otherwise, a value of-1 is returned and errno is set 
to indicate the error. 

ERRORS 

Stat and Istat will fail if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[EPERM] The pathname contains a character with the high-order bit set 

[ENAMETOOLONG] 

The pathname was too long. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied for a component of the path prefix. 

[EFAULT] Buf or name points to an invalid address. 

[ELOOP] Too many symbolic links were encountered in translating the pathname. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

Fstat will fail if one or both of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[EFAULT] Buf points to an invalid address. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

CAVEAT 

The fields in the stat structure currently marked st_sparel , st_spare2, and st_spare3 are present in prepara- 
tion for inode time stamps expanding to 64 bits. This, however, can break certain programs which depend 
on the time stamps being contiguous (in calls to utimes( 2)). 

SEE ALSO 

chmod(2), chown(2), utimes(2) 

BUGS 

Applying to a socket returns a zero’d buffer. 
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NAME 

statfs - get file system statistics 

SYNOPSIS 

#include <sys/vfs.h> 

statfs(path, buf) 
char *path; 
struct statfs *buf; 

fstatfs(fd, buf) 
int fd; 

struct statfs *buf; 

DESCRIPTION 

Statfs returns information about a mounted file system. Path is the pathname of any file within the 
mounted filesystem. Buf is a pointer to a statfs structure defined as follows: 

typedef struct { 

long val[2]; 

} fsidt; 

struct statfs { 

long f type; /* type of info, zero for now */ 

long fbsize; /* fundamental file system block size */ 

long f blocks; /* total blocks in file system */ 

long fbfree; I* free blocks */ 

long f bavail; /* free blocks available to non-superuser */ 

long f files; /* total file nodes in file system */ 

long f ffree; /* free file nodes in fs */ 

fsid t f fsid; /* file system id */ 
long f_spare[7]; /* spare for later */ 

}; 

Fields that are undefined for a particular file system are set to -1. F statfs returns the same information 
about an open file referenced by descriptor fd. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, -1 is returned and the global variable 
err no is set to indicate the error. 

ERRORS 

Statfs fails if one or more of the following are true: 

[ENOTDIR] A component of the path prefix is not a directory. 

[EPERM] The pathname contains a character with the high-order bit set. 

[ENAMETOOLONG] 

The pathname was too long. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied for a component of the path prefix. 

[EFAULT] Buf or name points to an invalid address. 

[ELOOP] Too many symbolic links were encountered in translating the pathname. 

[EIO] An I/O error occurred while reading from or writing to the file system. 
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Fstatfs fails if one or both of the following are true: 

[EBADF] Fildes is not a valid open file descriptor. 

[EFAULT] Buf points to an invalid address. 

[EIO] An I/O error occurred while reading from or writing to the file system. 
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NAME 

swapon - add a swap device for interleaved paging/swapping 

SYNOPSIS 

swapon(special) 
char *special; 

DESCRIPTION 

Swapon makes the block device special available to the system for allocation for paging and swapping. 
The names of potentially available devices are known to die system and defined at system configuration 
time. The size of the swap area on special is calculated at the time the device is first made available for 
swapping. 

SEE ALSO 

swapon(8), config(8) 


ERRORS 

[ENOTDIR] A component of the path prefix is not a directory. 

[EPERM] The pathname contains a character with the high-order bit set. 

[ENAMETOOLONG] 

The pathname was too long. 


[ENOENT] 

[EACCES] 

[EFAULT] 

[ELOOP] 

[ENOTBLK] 

[ENXIO] 


Special does not exist 

Search permission is denied for a component of the path prefix. 

Special points to an invalid address. 

Too many symbolic links were encountered in translating the pathname. 

Special is not a block device. 

The major device number of special is out of range (this indicates no device driver exists 
for the associated hardware). 


[EBUSY] The device specified by special has already been made available for swapping. 

[ENODEV] The device specified by special was not configured into the system as a swap device. 

[EIO] An I/O error occurred while reading from or writing to the file system. 


BUGS 

There is no way to stop swapping on a disk so that the pack may be dismounted. 
This call will be upgraded in future versions of the system. 
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NAME 

symlink - make symbolic link to a file 
SYNOPSIS 

symlink(namel, name2) 
char *namel, *name2; 

DESCRIPTION 

A symbolic link name2 is created to name! ( name! is the name of the file created, namel is the string used 
in creating the symbolic link). Either name may be an arbitrary path name; the files need not be on the 
same file system. 

RETURN VALUE 

Upon successful completion, a zero value is returned. If an error occurs, the error code is stored in errno 
and a -1 value is returned. 

ERRORS 

The symbolic link is made unless on or more of the following are true: 

[EPERM] name2 contains a character with the high-order bit set. 

[EINVAL] invalid argument. 

[ENAMETOOLONG] 

One of the pathnames specified was too long. 

[ENOTDIR] A component of the name2 prefix is not a directory. 

[EEXIST] Name2 already exists. 

[EACCES] A component of the name2 path prefix denies search permission. 

[EROFS] The file name2 would reside on a read-only file system. 

[EFAULT] Namel or name2 points outside the process’s allocated address space. 

[ELOOP] Too may symbolic links were encountered in translating the pathname. 

[ENOSPC] The directory in which the entry for the new symbolic link is being placed cannot be 

extended because there is no space left on the file system containing the directory. 

[ENOSPC] The new symbolic link cannot be created because there is no space left on the file system 
which will contain the link. 

[ENOSPC] There are no free inodes on the file system on which the file is being created. 

[EDQUOT] The directory in which the entry for the new symbolic link is being placed cannot be 

extended because the user’s quota of disk blocks on the file system containing the direc- 
tory has been exhausted. 

[EDQUOT] The new symbolic link cannot be created becaue the user’s quota of disk blocks on the 
file system which will contain the link has been exhausted. 

[EDQUOT] The user’s quota of inodes on the file system on which the file is being created has been 
exhausted. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

SEE ALSO 

link(2), ln(l), unlink(2) 
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NAME 

sync - update super-block 

SYNOPSIS 

sync() 

DESCRIPTION 

Sync causes all information in core memory that should be on disk to be written out. This includes 
modified super blocks, modified i-nodes, and delayed block I/O. 

Sync should be used by programs which examine a file system, for example fsck, df, etc. Sync is mandatory 
before a boot. . 

SEE ALSO 

fsync(2), sync(8), cron(8) 

BUGS 

The writing, although scheduled, is not necessarily complete upon return from sync. 
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NAME 

syscall - indirect system call 
SYNOPSIS 

syscall(number, arg, ...) 

DESCRIPTION 

Syscall performs the system call whose assembly language interface has the specified number, and argu- 
ments arg .... 

The register dO value of the system call is returned. 

DIAGNOSTICS 

When the C-bit is set, syscall returns -1 and sets the external variable errno (see intro (2)). 

BUGS 

There is no way to simulate system calls such as pipe (2), which return values in register dl. 
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NAME 

truncate, ftruncate - truncate a file to a specified length 
SYNOPSIS 

truncate(path, length) 
char *path; 
unsigned long length; 

ftruncate(fd, length) 
int fd; 

unsigned long length; 

DESCRIPTION 

Truncate causes the file named by path or referenced by fd to be truncated to at most length bytes in size. 
If the file previously was larger than this size, the extra data is lost. With ftruncate , the file must be open 
for writing. 

RETURN VALUES 

A value of 0 is returned if the call succeeds. If the call fails a -1 is returned, and the global variable errno 
specifies the error. 

ERRORS 

Truncate succeeds unless: 


[EPERM] The pathname contains a character with the high-order bit set 

[ENAMETOOLONG] 

The pathname was too long. 

[ENOTDIR] A component of the path prefix of path is not a directory. 

[ENOENT] The named file does not exist. 

[EACCES] Either search permission is denied by a component of the path or the file exists, but is 
unwritable. 


[EISDIR] 

[EROFS] 

[ETXTBSY] 

[EFAULT] 

[EIO] 


The named file is a directory. 

The named file resides on a read-only file system. 

The file is a pure procedure (shared text) file that is being executed. 
Path points outside the process’s allocated address space. 

An I/O error occurred while reading from or writing to the file system. 


Ftruncate succeeds unless: 


[EBADF] The fd is not a valid descriptor of a file open for writing. 

[EINVAL] The fd references a socket, not a file. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

SEE ALSO 

open(2) 

BUGS 

Partial blocks discarded as the result of truncation are not zero filled; this can result in holes in files which 
do not read as zero. 


These calls should be generalized to allow ranges of bytes in a file to be discarded. 
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NAME 

umask - set file creation mode mask 
SYNOPSIS 

oumask = umask(numask) 
int oumask, numask; 

DESCRIPTION 

Umask sets the process’s file mode creation mask to numask and returns the previous value of the mask. 
The low-order 9 bits of numask are used whenever a file is created, clearing corresponding bits in the file 
mode (see chmod( 2)). This clearing allows each user to restrict the default access to his files. 

The value is initially 022 (write access for owner only). The mask is inherited by child processes. 

RETURN VALUE 

The previous value of the file mode mask is returned by the call. 

SEE ALSO 

chmod(2), mknod(2), open(2) 
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NAME 

unlink - remove directory entry 

SYNOPSIS 

unlink(path) 
char *path; 

DESCRIPTION 

Unlink removes the entry for the file path from its directory. If this entry was the last link to the file, and 
no process has the file open, then all resources associated with the file are reclaimed. If, however, the file 
was open in any process, the actual resource reclamation is delayed until it is closed, even though the direc- 
tory entry has disappeared. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set 
to indicate the error. 

ERRORS 

The unlink succeeds unless: 

[EPERM] The path contains a character with the high-order bit set. 

[ENAMETOOLONG] 

The path name is too long. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] The named file does not exist. 

[EACCES] Search permission is denied for a component of the path prefix. 

[EACCES] Write permission is denied on the directory containing the link to be removed. 

[EPERM] The named file is a directory and the effective user ID of the process is not the super- 

user. 

[EBUSY] The entry to be unlinked is the mount point for a mounted file system. 

[EROFS] The named file resides on a read-only file system. 

DEFAULT] Path points outside the process’s allocated address space. 

[ELOOP] Too many symbolic links were encountered in translating the pathname. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

SEE ALSO 

close(2), link(2), rmdir(2) 
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NAME 

unmount - remove a file system 

SYNOPSIS 

unmount(name) 
char *name; 

DESCRIPTION 

Unmount announces to the system that the directory name is no longer to refer to the root of a mounted file 
system. The directory name reverts to its ordinary interpretation. 

RETURN VALUE 

Unmount returns 0 if the action occurred; -1 if if the directory is inaccessible or does not have a mounted 
file system, or if there are active files in the mounted file system. 

ERRORS 

Unmount may fail with one of the following errors: 

[EPERM] The caller is not the super-user. 

[EINVAL] Name is not the root of a mounted file system. 

[EBUSY] A process is holding a reference to a file located on the file system. 

[ENOTDIR] A component of the path prefix is not a directory. 

[EPERM] The pathname contains a character with the high-order bit set. 

[ENAMETOOLONG] 

The pathname was too long. 

[ENOENT] name does not exist. 

[EACCES] Search permission is denied for a component of the path prefix. 

[EFAULT] name points outside the process’s allocated address space. 

[ELOOP] Too many symbolic links were encountered in translating the pathname. 

[EIO] An I/O error occurred while reading from or writing to the file system. 

SEE ALSO 

mount(2), mount(8), umount(8) 

BUGS 

The error codes are in a state of disarray; too many errors appear to the caller as one value. 
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NAME 

utimes - set file times 
SYNOPSIS 

#include <sys/types.h> 

utimes(file, tvp) 
char *file; 

struct timeval *tvp[2]; 

DESCRIPTION 

The utimes call uses the “accessed” and “updated” times in that order from the tvp vector to set the 
corresponding recorded times for file. 

The caller must be the owner of the file or the super-user. The “inode-changed” time of the file is set to 
the current time. 

RETURN VALUE 

Upon successful completion, a value of 0 is returned. Otherwise, a value of-1 is returned and errno is set 
to indicate the error. 

ERRORS 

Utime will fail if one or more of the following are true: 

[EPERM] The pathname contained a character with the high-order bit set. 

[ENAMETOOLONG] 

The pathname was too long. 

The named file does not exist. 

A component of the path prefix is not a directory. 

A component of the path prefix denies search permission. 

The process is not super-user and not the owner of the file. 

The file system containing the file is mounted read-only. 

File or tvp points outside the process’s allocated address space. 

Too many symbolic links were encountered in translating the pathname. 

An I/O error occurred while reading from or writing to the file system. 

SEE ALSO 

stat(2) 


[ENOENT] 

[ENOTDIR] 

[EACCES] 

[EPERM] 

[EROFS] 

[EFAULT] 

[ELOOP] 

[EIO] 
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NAME 

vadvise - give advice to paging system 
SYNOPSIS 

#include <sys/vadvise.h> 

vadvise(param) 
int param; 

DESCRIPTION 

Vadvise is used to inform the system that process paging behavior merits special consideration. Parameters 
to vadvise are defined in the file <vadvise.h>. Currently, two calls t vadvise are implemented. 

The call 


vadvise(VA_ANOM); 

advises that the paging behavior is not likely to be well handled by the system’s default algorithm, since 
reference information is collected over macroscopic intervals (e.g. 10-20 seconds) will not serve to indicate 
future page references. The system in this case will choose to replace pages with little emphasis placed on 
recent usage, and more emphasis on referenceless circular behavior. It is essential that processes which 
have very random paging behavior (such as LISP during garbage collection of very large address spaces) 
call vadvise, as otherwise the system has great difficulty dealing with their page-consumptive demands. 

The call 


vadvise(VA_NORM); 

restores default paging replacement behavior after a call to 
vadvise(VA_ANOM); 

BUGS 

Will go away soon, being replaced by a per-page madvise facility. 
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NAME 

vfork - spawn new process in a virtual memory efficient way 

SYNOPSIS 

pid = vfork() 
int pid; 

DESCRIPTION 

Vfork can be used to create new processes without fully copying the address space of the old process, 
which is horrendously inefficient in a paged environment. It is useful when the purpose of fork( 2) would 
have been to create a new system context for an execve . Vfork differs from fork in that the child borrows 
the parent’s memory and thread of control until a call to execve (2) or an exit (either by a call to exit (2) or 
abnormally.) The parent process is suspended while the child is using its resources. 

Vfork returns 0 in the child’s context and (later) the pid of the child in the parent’s context. 

Vfork can normally be used just like fork. It does not work, however, to return while running in the childs 
context from the procedure which called v fork since the eventual return from vfork would then return to a 
no longer existent stack frame. Be careful, also, to call exit rather than exit if you can’t execve, since exit 
will flush and close standard I/O channels, and thereby mess up the parent processes standard I/O data 
structures. (Even with fork it is wrong to call exit since buffered data would then be flushed twice.) 

SEE ALSO 

fork(2), execve(2), sigvec(2), wait(2), 

DIAGNOSTICS 

Same as for fork. 

BUGS 

This system call will be eliminated when proper system sharing mechanisms are implemented. Users 
should not depend on the memory sharing semantics of vfork as it will, in that case, be made synonymous 
to fork. 

To avoid a possible deadlock situation, processes which are children in the middle of a y fork are never sent 
SIGTTOU or SIGTTIN signals; rather, output or iocth are allowed and input attempts result in an end-of- 
file indication. 
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NAME 

vhangup - virtually “hangup” the current control terminal 
SYNOPSIS 

vhangupO 

DESCRIPTION 

Vhangup, is used by the initialization process mzf(8) (among others) to arrange that users are given 
clean’” terminals at login, by revoking access of the previous users’ processes to the terminal. To effect 
this, vhangup searches the system tables for references to the control terminal of the invoking process, 
revoking access permissions on each instance of the terminal which it finds. Further attempts to access the 
terminal by the affected processes will yield i/o errors (EBADF). Finally, a hangup signal (SIGHUP) is 
sent to the process group of the control terminal. 

SEE ALSO 

init (8) 

BUGS 

Access to the control terminal via /dev/tty is still possible. 

This call should be replaced by an automatic mechanism which takes place on process exit. 
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NAME 

wait, wait3 - wait for process to terminate or stop 
SYNOPSIS 

#include <sys/wait.h> 

pid = wait(status) 
imii pid; 

union wait ^status; 

pid = wait(O) 
int pid; 

#include <sys/time.b> 

#include <sys/resource.h> 

pid = wait3(status, options, rusage) 
int pid; 

union wait ^status; 

int options; 

struct rusage *rusage; 

DESCRIPTION 

Wait causes its caller to delay until a signal is received or one of its child processes terminates or stops due 
to tracing. If any child has died or stopped due to tracing and this has not been reported via wait, return is 
immediate, returning the process id and exit status of one of those children. If that child had died, it is dis- 
carded. If there are no children, return is immediate with the value -1 returned. If there are only running 
or stopped but reported children, the calling processes is suspended. 

On return from a successful wait call, status is nonzero, and the high byte of status contains the low byte of 
the argument to exit supplied by the child process; the low byte of status contains the termination status of 
the process. A more precise definition of the status word is given in <syslwait.h>. 

Wait3 is an alternate interface which allows both non-blocking status collection and the status of children 
stopped by any means. The status parameter is defined as above. The options parameter is used to indicate 
the call should not block if there are no processes which have status to report (WNOHANG), and/or that 
children of the current process which are stopped due to a SIGTTIN, SIGTTOU, SIGTSTP, or SIGSTOP 
signal are eligible to have their status reported as well (WUNTRACED). A terminated child is discarded 
after it reports status, and a stopped process will not report its status more than once. If rusage is non-zero, 
a summary of the resources used by the terminated process and all its children is returned. (This informa- 
tion is currently not available for stopped processes.) 

When the WNOHANG option is specified and no processes have status to report, wait3 returns a pid of 0. 
The WNOHANG and WUNTRACED options may be combined by or’ ing the two values. 

NOTES 

See sigvec (2) for a list of termination statuses (signals); 0 status indicates normal termination. A special 
status (0177) is returned for a stopped process which has not terminated and can be restarted; see ptrace(2) 
and sigvec (2). If the 0200 bit of the termination status is set, a core image of the process was produced by 
the system. 

If the parent process terminates without waiting on its children, the initialization process (process ID = 1) 
inherits the children. 

Wait and wait3 are automatically restarted when a process receives a signal while awaiting termination of a 
child process. 

RETURN VALUE 

If wait returns due to a stopped due to tracing or terminated child process, the process ID of the child is 
returned to the calling process. Otherwise, a value of-1 is returned and errno is set to indicate the error. 
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Wait3 returns -1 if there are no children not previously waited for; 0 is returned if WNOHANG is 
specified and there are no stopped or exited children. 

ERRORS 

Wait will fail and return immediately if one or more of the following are true: 

[ECHILD] The calling process has no existing unwaited-for child processes. 

[EFAULT] The status or rusage arguments point to an illegal address. 

SEE ALSO 

exit(2) 
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NAME 

write, writev - write on a file 

SYNOPSIS 

write(d, buf, nbytes) 
int d; 

char *buf; 
int nbytes; 

#include <sys/types.h> 

#include <sys/uio.h> 

writev(d, iov, ioveclen) 
int d; 

struct iovec *iov; 
int ioveclen; 

DESCRIPTION 

Write attempts to write nbytes of data to the object referenced by the descriptor d from the buffer pointed to 
by buf. Writev performs the same action, but gathers the output data from the iovlen buffers specified by 
the members of the iov array; iov[0], iov[l], etc. 

On objects capable of seeking, the write starts at a position given by the pointer associated with d, see 
lseek( 2). Upon return from write, the pointer is incremented by the number of bytes actually written. 

Objects that are not capable of seeking always write from the current position. The value of the pointer 
associated with such an object is undefined. 

If the real user is not the super-user, then write clears the set-user-id bit on a file. This prevents penetration 
of system security by a user who “captures” a writable set-user-id file owned by the super-user. 

RETURN VALUE 

Upon successful completion the number of bytes actually writen is returned. Otherwise a -I is returned 
and errno is set to indicate the error. 

ERRORS 

Write will fail and the file pointer will remain unchanged if one or more of the following are true: 

[EBADF] D is not a valid descriptor open for writing. 

[EPIPE] An attempt is made to write to a pipe that is not open for reading by any process (or to a 

socket of type SOCK_STREAM that is connected to a peer socket.) Note: an attempted 
write of this kind will also cause you to recieve a SIGPIPE signal from the kemal. If 
you’ve not made a special provision to catch or ignore this signal, you will die. 

[EFBIG] An attempt was made to write a file that exceeds the process’s file size limit or the max- 

imum file size. 

[EFAULT] Part of iov or data to be written to the file points outside the process’s allocated address 
space. 

[ENOSPC] There is no free space remaining on the file system containing the file. 

[EDQUOT] The user’s quota of disk blocks on the file system containing the file has been exhausted. 
[EIO] An I/O error occurred while reading from or writing to the file system. 

SEE ALSO 

lseek(2), open(2), pipe(2) 
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NAME 

intro - introduction to library functions 
DESCRIPTION 

Section 3 describes library routines. The main C library is llibllibc.a, which contains all system call entry 
points described in section 2, as well as functions described in several subsections here. The primary func- 
tions are described in the main section 3. Functions associated with the “standard I/O library” used by 
many C programs are found in section 3S. The main C library also includes Internet network functions, 
described in section 3N, and routines providing compatibility with other UNIX systems, described in sec- 
tion 3C. 

Other sections are: 

(3F) AJ1 functions callable from FORTRAN. These manual pages are reproduced in the FORTRAN 
manual. These functions perform the same jobs as the straight “3” functions do for C program- 
mers. There are in fact three FORTRAN libraries, namely -1U77 which contains the system inter- 
face routines, -1177 which is the I/O interface library, and -1F77 which is everything not con- 
tained in the other two. These libraries are searched automatically by the loader when loading 
FORTRAN programs. 

(3M) The math library. C declarations for the types of functions may be obtained from the include file 
<math.h>. To use these functions with C programs use a -1m option with cc(l). They are 
automatically loaded as needed by the Fortran and Pascal compilers /77(1) and pc( 1). 

(3X) Various specialized libraries have not been given distinctive captions. Files in which such 
libraries are found are named on appropriate pages if they don’t appear in the libc library. 

FILES 

/lib/libc.a 
/usr/lib/libc_p.a 
/usr/lib/libm.a 
/usr/lib/libmjp.a 
/usr/lib/libU77.a 
/usr/lib/libI77.a 
/usr/lib/libF77.a 
/usr/lib/libcurses.a 
/usr/lib/libdbm.a 
/usr/lib/libmp.a 
/usr/lib/libtermcap.a 
/usr/lib/libtermcapjp.a 
/usr/lib/libtermlib 
/usr/lib/libtermlib_p.a 
/usr/lib/libplot.a 
/usr/lib/lib300.a 
/usr/lib/lib 3 00s . a 
/usr/lib/lib4014.a 
/usr/lib/lib450.a 

SEE ALSO 

intro(3C), intro(3S), intro(3F), intro(3M), intro(3N), nm(l), ld(l), cc(l), f77(l), intro(2) 

DIAGNOSTICS 

Functions in the math library (section 3M) may return conventional values when the function is undefined 
for the given arguments or when the value is not representable. In these cases the external variable errno 
(see intro(2 )) is set to the value EDOM (domain error) or ERANGE (range error). The values of EDOM 
and ERANGE are defined in the include file <errno.h>. 


C Library ((2), (3), (3N) and (3C) routines) 
Profiling C library (for gprof(l)) 

Math Library -1m (see section 3M) 

Profiling version of -lm 

FORTRAN system interface (see section 3F) 

FORTRAN I/O (see section 3F) 

FORTRAN everything else (see section 3F) 
screen management routines (see curses (3X) 
data base management routines (see dbm( 3X)) 
multiple precision math library (see mp( 3X)) 
terminal handling routines (see termcap{ 3X)) 

t» 

it 

it 

plot routines (see plot{ 3X)) 

ti 

ii 

it 

it 
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LIST OF FUNCTIONS 


Name 

Appears on Page 

abort 

abort.3 

abs 

abs.3 

addmntent 

getmntent.3 

alarm 

alarm.3c 

alphasort 

scandir.3 

asctime 

ctime.3 

assert 

assert.3 

atof 

atof.3 

atoi 

atof.3 

atol 

atof.3 

bcmp 

bstring.3 

bcopy 

bstring.3 

bzero 

bstring.3 

clearerr 

ferror.3s 

closedir 

directory.3 

closelog 

syslog.3 

crypt 

crypt.3 

crime 

ctime.3 

dysize 

crime.3 

ecvt 

ecvt.3 

edata 

end.3 

encrypt 

crypt.3 

end 

end.3 

endfsent 

getfsent.3 

endgrent 

getgrent.3 

endhostent 

gethostent.3n 

endmntent 

getmntent.3 

endnetent 

getnetent.3n 

endprotoent 

getprotoent.3n 

endpwent 

getpwent.3 

endservent 

getservent.3n 

environ 

execl.3 

ermo 

perror.3 

etext 

end.3 

execl 

execl.3 

execle 

execl.3 

execlp 

execl.3 

execv 

execl.3 

execvp 

execl.3 

exit 

exit.3 

fclose 

fclose.3s 

fcvt 

ecvt.3 

fdopen 

fopen.3s 

feof 

ferror.3s 

ferror 

ferror.3s 

fflush 

fclose.3s 

ffs 

bstring.3 

fgetc 

getc.3s 

fgets 

gets.3s 

fileno 

ferror.3s 

fopen 

fopen.3s 


Description 

generate a fault 

integer absolute value 

get file system descriptor file entry 

schedule signal after specified time 

scan a directory 

convert date and time to ASCII 

program verification 

convert ASCII to numbers 

convert ASCII to numbers 

convert ASCII to numbers 

bit and byte string operations 

bit and byte string operations 

bit and byte string operations 

stream status inquiries 

directory operations 

control system log 

DES encryption 

convert date and time to ASCII 

convert date and time to ASCII 

output conversion 

last locations in program 

DES encryption 

last locations in program 

get file system descriptor file entry 

get group file entry 

get network host entry 

get file system descriptor file entry 

get network entry 

get protocol entry 

get password file entry 

get service entry 

execute a file 

system error messages 

last locations in program 

execute a file 

execute a file 

execute a file 

execute a file 

execute a file 

terminate a process after performing cleanup 

close or flush a stream 

output conversion 

open a stream 

stream status inquiries 

stream status inquiries 

close or flush a stream 

bit and byte string operations 

get character or integer from stream 

get a string from a stream 

stream status inquiries 

open a stream 
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fprintf 

printf.3s 

formatted output conversion 

fputc 

putc.3s 

put character or word on a stream 

fputs 

puts.3s 

put a string on a stream 

fread 

fread.3s 

buffered binary input/output 

freopen 

fopen.3s 

open a stream 

frexp 

frexp.3 

split into mantissa and exponent 

fscanf 

scanf.3s 

formatted input conversion 

fseek 

fseek.3s 

reposition a stream 

ftell 

fseek.3s 

reposition a stream 

ftime 

time.3c 

get date and time 

fwrite 

fread.3s 

buffered binary input/output 

gcvt 

ecvt.3 

output conversion 

getc 

getc.3s 

get character or integer from stream 

getchar 

getc.3s 

get character or integer from stream 

getenv 

getenv.3 

value for environment name 

getfsent 

getfsent.3 

get file system descriptor file entry 

getfsfile 

getfsent.3 

get file system descriptor file entry 

getfsspec 

getfsent.3 

get file system descriptor file entry 

getfstype 

getfsent.3 

get file system descriptor file entry 

getgrent 

getgrent.3 

get group file entry 

getgrgid 

getgrent.3 

get group file entry 

getgmam 

getgrent.3 

get group file entry 

gethostbyaddr 

gethostent.3n 

get network host entry 

gethostbyname 

gethostent.3n 

get network host entry 

gethostent 

gethostent.3n 

get network host entry 

getlogin 

getlogin.3 

get login name 

getmntent 

getmntent.3 

get file system descriptor file entry 

getnetbyaddr 

getnetent.3n 

get network entry 

getnetbyname 

getnetent.3n 

get network entry 

getnetent 

getnetent.3n 

get network entry 

getopt 

getopt.3c 

get option letter from argv 

getpass 

getpass.3 

read a password 

getprotobyname 

getprotoent.3n 

get protocol entry 

getprotobynumber 

getprotoent.3n 

get protocol entry 

getprotoent 

getprotoent.3n 

get protocol entry 

getpw 

getpw. 3 

get name from uid 

getpwent 

getpwent.3 

get password file entry 

getpwnam 

getpwent.3 

get password file entry 

getpwuid 

getpwent.3 

get password file entry 

gets 

gets.3s 

get a string from a stream 

getservbyname 

getservent.3n 

get service entry 

getservbyport 

getservent.3n 

get service entry 

getservent 

getservent.3n 

get service entry 

getw 

getc.3s 

get character or integer from stream 

getwd 

getwd.3 

get current working directory pathname 

gmtime 

ctime.3 

convert date and time to ASCII 

gtty 

stty.3c 

set and get terminal state 

hasmntopt 

getmntent.3 

get file system descriptor file entry 

htonl 

byteorder.3n 

convert values between host and network byte order 

htons 

byteorder.3n 

convert values between host and network byte order 

index 

string.3 

string operations 

inet_addr 

inet.3n 

Internet address manipulation 

inet_lnaof 

inet.3n 

Internet address manipulation 
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inetmakeaddr 

inet.3n 

Internet address manipulation 

inetnetof 

inet.3n 

Internet address manipulation 

inetnetwork 

inet3n 

Internet address manipulation 

inetntoa 

inet.3n 

Internet address manipulation 

initgroups 

initgroups.3 

initialize group access list 

initstate 

random.3 

better random number generator; routines for changing generators 

insque 

insque.3 

insert/remove element from a queue 

isalnum 

ctype.3 

character classification and conversion macros 

isalpha 

ctype.3 

character classification and conversion macros 

isascii 

ctype.3 

character classification and conversion macros 

isatty 

ttyname.3 

find name of a terminal 

iscntrl 

ctype.3 

character classification and conversion macros 

isdigit 

ctype.3 

character classification and conversion macros 

isgraph 

ctype.3 

character classification and conversion macros 

isinf 

isinf.3 

test for indeterminate floating point values 

islower 

ctype.3 

character classification and conversion macros 

isnan 

isinf.3 

test for indeterminate floating point values 

isprint 

ctype.3 

character classification and conversion macros 

ispunct 

ctype.3 

character classification and conversion macros 

isspace 

ctype.3 

character classification and conversion macros 

isupper 

ctype.3 

character classification and conversion macros 

isxdigit 

ctype.3 

character classification and conversion macros 

ldexp 

frexp.3 

split into mantissa and exponent 

localtime 

ctime.3 

convert date and time to ASCII 

longjmp 

setjmp.3 

non-local goto 

mktemp 

mktemp.3 

make a unique file name 

modf 

frexp.3 

split into mantissa and exponent 

moncontrol 

monitor.3 

prepare execution profile 

monitor 

monitor.3 

prepare execution profile 

monstartup 

monitor.3 

prepare execution profile 

nice 

nice.3c 

set program priority 

nlist 

nlist.3 

get entries from name list 

ntohl 

byteorder.3n 

convert values between host and network byte order 

ntohs 

byteorder.3n 

convert values between host and network byte order 

onexit 

onexit.3 

name termination handler 

opendir 

directory.3 

directory operations 

openlog 

syslog.3 

control system log 

optarg 

getopt.3c 

get option letter from argv 

optind 

getopt.3c 

get option letter from argv 

pause 

pause.3c 

stop until signal 

pclose 

popen.3s 

initiate I/O to/from a process 

perror 

perror.3 

system error messages 

popen 

popen.3s 

initiate I/O to/from a process 

printf 

printf.3s 

formatted output conversion 

psignal 

psignal.3 

system signal messages 

putc 

putc.3s 

put character or word on a stream 

putchar 

putc.3s 

put character or word on a stream 

puts 

puts.3s 

put a string on a stream 

putw 

putc.3s 

put character or word on a stream 

qsort 

qsort.3 

quicker sort 

rand 

rand.3c 

random number generator 

random 

random.3 

better random number generator; routines for changing generators 

rcmd 

rcmd.3n 

routines for returning a stream to a remote command 
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recomp 

regex.3 

regular expression handler 

reexec 

regex.3 

regular expression handler 

readdir 

directory.3 

directory operations 

remque 

insque.3 

insert/remove element from a queue 

rewind 

fseek.3s 

reposition a stream 

rewinddir 

directory.3 

directory operations 

rexec 

rexec.3n 

return stream to a remote command 

rindex 

string.3 

string operations 

rresvport 

rcmd.3n 

routines for returning a stream to a remote command 

ruserok 

rcmd.3n 

routines for returning a stream to a remote command 

scandir 

scandir.3 

scan a directory 

scanf 

scanf.3s 

formatted input conversion 

seekdir 

directory.3 

directory operations 

setbuf 

setbuf.3s 

assign buffering to a stream 

setbuffer 

setbuf.3s 

assign buffering to a stream 

setegid 

setuid.3 

set user and group ID 

seteuid 

setuid.3 

set user and group ID 

setfsent 

getfsent.3 

get file system descriptor file entry 

setgid 

setuid.3 

set user and group ID 

setgrent 

getgrent.3 

get group file entry 

sethostent 

gethostent.3n 

get network host entry 

setjmp 

setjmp.3 

non-local goto 

setkey 

crypt. 3 

DES encryption 

setlinebuf 

setbuf.3s 

assign buffering to a stream 

setmntent 

getmntent3 

get file system descriptor file entry 

setnetent 

getnetent.3n 

get network entry 

setprotoent 

getprotoent.3n 

get protocol entry 

setpwent 

getpwent.3 

get password file entry 

setrgid 

setuid.3 

set user and group ID 

setruid 

setuid.3 

set user and group ID 

setservent 

getservent.3n 

get service entry 

setstate 

random.3 

better random number generator; routines for changing generators 

setuid 

setuid.3 

set user and group ID 

signal 

signal.3 

simplified software signal facilities 

sleep 

sleep.3 

suspend execution for interval 

sprintf 

printf.3s 

formatted output conversion 

srand 

rand.3c 

random number generator 

srandom 

random.3 

better random number generator; routines for changing generators 

sscanf 

scanf.3s 

formatted input conversion 

stdio 

intro.3s 

standard buffered input/output package 

strcat 

string.3 

string operations 

strcmp 

string.3 

string operations 

strcpy 

string.3 

string operations 

strlen 

string.3 

string operations 

stmcat 

string.3 

string operations 

stmcmp 

string.3 

string operations 

stmcpy 

string.3 

string operations 

stty 

stty .3c 

set and get terminal state 

swab 

swab.3 

swap bytes 

syserrlist 

perror.3 

system error messages 

sys_nerr 

perror.3 

system error messages 

sys_siglist 

psignal.3 

system signal messages 

syslog 

syslog.3 

control system log 
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system 

system.3 

issue a shell command 

telldir 

directory.3 

directory operations 

time 

time.3c 

get date and time 

times 

times.3c 

get process times 

timezone 

ctime.3 

convert date and time to ASCII 

tmpnam 

tmpnam.3c 

create a name for a temporary file 

toascii 

ctype.3 

character classification and conversion macros 

tolower 

ctype.3 

character classification and conversion macros 

toupper 

ctype.3 

character classification and conversion macros 

ttyname 

ttyname.3 

find name of a terminal 

ttyslot 

ttyname.3 

find name of a terminal 

ulimit 

ulimit3c 

get and set user limits 

ungetc 

ungetc.3s 

push character back into input stream 

utime 

utime.3c 

set file times 

valloc 

valloc.3 

aligned memory allocator 

varargs 

varargs.3 

variable argument list 

vlimit 

vlimit.3c 

control maximum system resource consumption 

vtimes 

vtimes.3c 

get information about resource utilization 
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NAME 

abort - generate a fault 

SYNOPSIS 

abort() 

DESCRIPTION 

Abort executes an instruction which is illegal in user mode. This causes a signal that normally terminates 
the process with a core dump, which may be used for debugging. 

SEE ALSO 

adb(lS), signal(3), exit(2) 

DIAGNOSTICS 

Usually “Illegal instruction (core dumped)” from the shell. 

BUGS 

The abort function does not flush standard I/O buffers. Use fflush as described in/c/ose(3S). 
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NAME 

abs — integer absolute value 

SYNOPSIS 

abs(i) 
int 5; 

DESCRIPTION 

Abs returns the absolute value of its integer operand. 

SEE ALSO 

floor(3M) for fabs 

BUGS 

Applying the abs function to the most negative integer generates a result which is the most negative 
integer. That is, abs(0x80000000) returns 0x80000000 as a result. 
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NAME 

assert - program verification 

SYNOPSIS 

#include <assert.h> 

assert(expression) 

DESCRIPTION 

Assert is a macro that indicates expression is expected to be true at this point in the program. It causes an 
exit {2) with a diagnostic comment on the standard output when expression is false (0). Compiling with the 
cc(l) option -DNDEBUG effectively deletes assert from the program. 

DIAGNOSTICS 

‘Assertion failed: file/line n.' F is the source file and n the source line number of the assert statement. 
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NAME 

atof, atoi, atol — convert ASCII to numbers 
SYNOPSIS 

double atof(nptr) 
char *nptr; 

atoi(nptr) 
char *nptr; 

long atol(nptr) 
char *nptr; 

DESCRIPTION 

These functions convert a string pointed to by nptr to floating, integer, and long integer representation 
respectively. The first unrecognized character ends the string. 

A to/ recognizes an optional string of spaces, then an optional sign, then a string of digits optionally contain- 
ing a decimal point, then an optional ‘e’ or ‘E’ followed by an optionally signed integer. 

Atoi and atol recognize an optional string of spaces, then an optional sign, then a string of digits. 

SEE ALSO 

scanf(3S) 

BUGS 

There are no provisions for overflow. 

Currently, atof performs highly inaccurate conversions of very large or very small numbers — on the order 
of 10**32 or its reciprocal. 
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NAME 

bcopy, bcmp, bzero, ffs - bit and byte string operations 
SYNOPSIS 

bcopy(bl, b2, length) 
char *bl, *b2; 
int length; 

bcmp(bl, b2, length) 
char *bl, *b2; 
int length; 

bzero(b, length) 
char *b; 
int length; 

ffs(i) 
int i; 

DESCRIPTION 

The functions bcopy, bcmp, and bzero operate on variable length strings of bytes. They do not check for 
null bytes as the routines in string (3) do. 

Bcopy copies length bytes from string bl to the string b2. Overlapping strings are handled correctly. 

Bcmp compares byte string bl against byte string b2, returning zero if they are identical, non-zero other- 
wise. Both strings are assumed to be length bytes long. 

Bzero places length 0 bytes in the string b. 

Ffs finds the first bit set in the argument passed it and returns the index of that bit Bits are numbered start- 
ing at 1 from the right. A return value of -1 indicates the value passed is zero. 

CAVEAT 

The bcmp and bcopy routines take parameters backwards from strcmp and strcpy. 
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NAME 

crypt, setkey, encrypt - DES encryption 
SYNOPSIS 

char *crypt(key, salt) 
char *key, *salt; 

setkey(key) 
char *key; 

encrypt(block, edflag) 
char * block; 

DESCRIPTION 

Crypt is the password encryption routine. It is based on the NBS Data Encryption Standard, with variations 
intended (among other things) to frustrate use of hardware implementations of the DES for key search. 

The first argument to crypt is normally a user’s typed password. The second is a 2-character string chosen 
from the set [a-zA-ZO-9./]. The salt string is used to perturb the DES algorithm in one of 4096 different 
ways, after which the password is used as the key to encrypt repeatedly a constant string. The returned 
value points to the encrypted password, in the same alphabet as the salt The first two characters are the 
salt itself. 

The other entries provide (rather primitive) access to the actual DES algorithm. The argument of setkey is 
a character array of length 64 containing only the characters with numerical value 0 and 1. If this string is 
divided into groups of 8, the low-order bit in each group is ignored, leading to a 56-bit key which is set into 
the machine. 

The argument to the encrypt entry is likewise a character array of length 64 containing 0’s and l’s. The 
argument array is modified in place to a similar array representing the bits of the argument after having 
been subjected to the DES algorithm using the key set by setkey. If edflag is 0, the argument is encrypted; if 
non-zero, it is decrypted. 

SEE ALSO 

passwd(l), passwd(5), login(l), getpass(3) 

BUGS 

The return value points to static data whose content is overwritten by each call. 
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NAME 

crime, localtime, gmtime, asctime, timezone, dysize - convert date and time to ASCII 

SYNOPSIS 

char *ctime(cIock) 
long *c!ock; 

#include <sys/time.h> 

struct tm *locaItime(cIock) 
long *cIock; 

struct tm *gmtime(clock) 
long *c!ock; 

char *asctime(tm) 
struct tm *tm; 

char *timezone(zone, dst) 

int dysize(y) 
inty; 

DESCRIPTION 

ctime retrieves a time pointed to by clock such as returned by time( 3C) or the tv_sec element of the struct 
timeval (filled in by gettimeofday(2)), that is, the number of seconds since Jan. 1, 1970, 00:00, Greenwich 
Mean Time. It converts this value into ASCII, and returns a pointer to a 26-character string of the form: 

Sun Sep 16 01:03:52 1973\n\0 

Each field has a constant width. Localtime and gmtime return pointers to structures containing the broken- 
down time. Localtime corrects for the time zone and possible daylight savings time; gmtime converts 
directly to GMT, which is the time UNIX uses. Asctime converts a broken-down time to ASCII and returns 
a pointer to a 26-character string. 

The structure declaration from the include file is: 

struct tm { 


int 

tmsec; 

int 

tm_min; 

int 

tmhour; 

int 

tmmday; 

int 

tm mon; 

int 

tmyear; 

int 

tmwday; 

int 

tm_yday; 

int 

tm_isdst; 


}; 

These quantities give the time on a 24-hour clock, day of month (1-31), month of year (0-11), day of week 
(Sunday = 0), year - 1900, day of year (0-365), and a flag that is nonzero if daylight saving time is in 
effect. 

When local time is called for, the program consults the system to determine the time zone and whether the 
U.S.A., Australian, Eastern European, Middle European, or Western European daylight saving time adjust- 
ment is appropriate. The program knows about various peculiarities in time conversion over the past 10-20 
years. 

Timezone returns the name of the time zone associated with its first argument, which is measured in 
minutes westward from Greenwich. If the second argument is 0, the standard name is used, otherwise the 
Daylight Saving version. If the required name does not appear in a table built into the routine, the differ- 
ence from GMT is produced; e.g. in Afghanistan timezone(-(60*4+30), 0) is appropriate because it is 4:30 
ahead of GMT and the string GMT+4:30 is produced. 
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Dysize returns the number of days in the argument year, either 365 or 366. 

SEE ALSO 

gettimeofday(2), time(3C) 

BUGS 

The return values point to static data. The contents are overwritten by each call. 
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NAME 

ctype isalpha, isupper, islower, isdigit, isxdigit, isalnum, isspace, ispunct, isprint, iscntrl, isascii, isgraph, 
toupper, tolower, toascii - character classification and conversion macros 

SYNOPSIS 

#include <ctype.h> 

isalpha(c) 


CHARACTER CLASSIFICATION MACROS 

These macros classify ASCII-coded integer values by table lookup. Each is a predicate returning nonzero 
for true, zero for false. Isascii is defined on all integer values; the rest are defined only where isascii(c) is 
true and on the single non- ASCII value EOF (see stdio (3S)). 

isalpha(c) c is a letter 

isupper(c) c is an upper case letter 

islower(c) c is a lower case letter 

isdigit(c) c is a digit 

isxdigit(c) c is a hexadecimal digit 

isalnum(c) c is an alphanumeric character, that is, c is a letter or a digit 
isspace(c) c is a space, tab, carriage return, newline, or formfeed 
ispunct(c) c is a punctuation character (neither control nor alphanumeric) 
isprint(c ) c is a printing character, code 040(8) (space) through 0176 (tilde) 
iscntrl(c) c is a delete character (0177) or ordinary control character (less than 040). 
isascii(c) c is an ASCII character, code less than 0200 

isgraph(c) c is a visible graphic character, code 041 (exclamation mark) through 0176 (tilde). 

CHARACTER CONVERSION MACROS 

These macros perform simple conversions on single characters. 

toupper(c) converts c to its upper-case equivalent Note that this only works where c is known to be 
a lower-case character to start with (presumably checked via islower). 

tolower(c) converts c to its lower-case equivalent. Note that this only works where c is known to be 
a upper-case character to start with (presumably checked via isupper). 

toascii(c) masks c with the correct value so that c is guaranteed to be an ASCII character in the 

range 0 thru 0x7f. 


SEE ALSO 

ascii(7) 
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NAME 

opendir, readdir, telldir, seekdir, rewinddir, closedir - directory operations 
SYNOPSIS 

#include <sys/dir.h> 

DIR *opendir(fiIename) 
char *filename; 

struct direct *readdir(dirp) 

DIR *dirp; 

long telldir(dirp) 

DIR *dirp; 

seekdir(dirp, loc) 

DIR *dirp; 
long loc; 

rewinddir(dirp) 

DIR *dirp; 

closedir(dirp) 

DIR *dirp; 

DESCRIPTION 

Opendir opens the directory named by filename and associates a directory stream with it. Opendir returns 
a pointer to be used to identify the directory stream in subsequent operations. The pointer NULL is 
returned if filename cannot be accessed or is not a directory, or if it cannot malloc{ 3) enough memory to 
hold the whole thing. 

Readdir returns a pointer to the next directory entry. It returns NULL upon reaching the end of the direc- 
tory or detecting an invalid seekdir operation. 

Telldir returns the current location associated with the named directory stream. 

Seekdir sets the position of the next readdir operation on the directory stream. The new position reverts to 
the one associated with the directory stream when the telldir operation was performed. Values returned by 
telldir are good only for the lifetime of the DIR pointer from which they are derived. If the directory is 
closed and then reopened, the telldir value may be invalidated due to undetected directory compaction. It 
is safe to use a previous telldir value immediately after a call to opendir and before any calls to readdir. 

Rewinddir resets the position of the named directory stream to the beginning of the directory. 

Closedir closes the named directory stream and frees the structure associated with the DIR pointer. 

Sample code which searchs a directory for entry “name” is: 

len = strlen(name); 
dirp = opendir("."); 

for (dp = readdir(dirp); dp != NULL; dp = readdir(dirp)) 

if (dp->d_namlen == len && !strcmp(dp->d_name, name)) { 
closedir(dirp); 
return FOUND; 

} 

closedir(dirp); 
return NOTFOUND; 

SEE ALSO 

open(2), close(2), read(2), lseek(2), getwd(3), dir(5) 

BUGS 

Old UNIX programs which examine directories should be converted to use this package, as the new direc- 
tory format is non-obvious. 
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NAME 

ecvt, fcvt, gcvt - output conversion 
SYNOPSIS 

char *ecvt(value, ndigit, decpt, sign) 

double value; 

int ndigit, * decpt, *sign; 

char *fcvt(value, ndigit, decpt, sign) 

double value; 

int ndigit, *decpt, *sign; 

char *gcvt(value, ndigit, buf) 
double value; 
char *buf; 

DESCRIPTION 

Ecvt converts the value to a null-terminated string of ndigit ASCII digits and returns a pointer thereto. The 
position of the decimal point relative to the beginning of the string is stored indirectly through decpt (nega- 
tive means to the left of the returned digits). If the sign of the result is negative, die word pointed to by 
sign is non-zero, otherwise it is zero. The low-order digit is rounded. 

Fcvt is identical to ecvt, except that the correct digit has been rounded for Fortran F-format output of the 
number of digits specified by ndigits. 

Gcvt converts the value to a null-terminated ASCII string in buf and returns a pointer to buf. It attempts to 
produce ndigit significant digits in Fortran F format if possible, otherwise E format, ready for printing. 
Trailing zeros may be suppressed. 

SEE ALSO 

isinf(3), printf(3S) 

BUGS 

The return values point to static data whose content is overwritten by each call. 
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NAME 

end, etext, edata — last locations in program 

SYNOPSIS 

extern end; 
extern etext; 
extern edata; 

DESCRIPTION 

These names refer neither to routines nor to locations with interesting contents. The address of etext is the 
first address above the program text, edata above the initialized data region, and end above the uninitialized 
data region. 

When execution begins, the program break coincides with end, but it is reset by the routines brk( 2), mal- 
standard input/output (stdio (3S)), the profile (-p) option of cc(l), etc. The current value of the pro- 
gram break is reliably returned by ‘sbrk(O)’, see brk( 2). 

SEE ALSO 

brk(2), malloc(3) 
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NAME 

execl, execv, execle, execlp, execvp, environ - execute a file 
SYNOPSIS 

execl(name, argO, argl, argn, 0) 
char *name, *arg0, *argl, ..., *argn; 

execv(name, argv) 
char *name, *argv[ ]; 

execle(name, argO, argl argn, 0, envp) 

char *name, *arg0, *argl, *argn, *envp[ ]; 

execlp(name, argO, argl, ..., argn, 0) 
char *name, *arg0, *argl *argn; 

execvp(name, argv) 
char *name, *argv[ ]; 

extern char **environ; 

DESCRIPTION 

These routines provide various interfaces to the execve system call. Refer to execve( 2) for a description of 
their properties; only brief descriptions are provided here. 

Exec in all its forms overlays the calling process with the named file, then transfers to the entry point of the 
core image of the file. There can be no return from a successful exec; the calling core image is lost 

The name argument is a pointer to the name of the file to be executed. The pointers arg[0], arg[l ] ... 
address null-terminated strings. Conventionally arg [0] is the name of the file. 

Two interfaces are available, execl is useful when a known file with known arguments is being called; the 
arguments to execl are the character strings constituting the file and the arguments; the first argument is 
conventionally the same as the file name (or its last component). A 0 argument must end the argument list 

The execv version is useful when the number of arguments is unknown in advance; the arguments to execv 
are the name of the file to be executed and a vector of strings containing the arguments. The last argument 
string must be followed by a 0 pointer. 

When a C program is executed, it is called as follows: 

main(argc, argv, envp) 
int argc; 

char **argv, **envp; 

where argc is the argument count and argv is an array of character pointers to the arguments themselves. 
As indicated, argc is conventionally at least one and the first member of the array points to a string contain- 
ing the name of the file. 

Argv is directly usable in another execv because argv [argc] is 0. 

Envp is a pointer to an array of strings that constitute the environment of the process. Each string consists 
of a name, an “=”, and a null-terminated value. The array of pointers is terminated by a null pointer. The 
shell sh(l) passes an environment entry for each global shell variable defined when the program is called. 
See environ (5) for some conventionally used names. The C run-time start-off routine places a copy of 
envp in the global cell environ, which is used by execv and execl to pass the environment to any subpro- 
grams executed by the current program. 

Execlp and execvp are called with the same arguments as execl and execv, but duplicate the shell’s actions 
in searching for an executable file in a list of directories. The directory list is obtained from the environ- 
ment. 
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FILES 

/bin/sh shell, invoked if command file found by execlp or execvp 
SEE ALSO 

execve(2), fork(2), environ(5), csh(l), sh(l) 

“UNIX Programming” in Programming Tools for the Sun Workstation, pp. 1-3. 

DIAGNOSTICS 

If the file cannot be found, if it is not executable, if it does not start with a valid magic number (see 
a.out(5)), if maximum memory is exceeded, or if the arguments require too much space, a return consti- 
tutes the diagnostic; the return value is —1. Even for the super-user, at least one of the execute-permission 
bits must be set for a file to be executed. 
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NAME 

exit - terminate a process after performing cleanup 

SYNOPSIS 

exit(status) 
int status; 

DESCRIPTION 

Exit terminates a process by calling exit (2) after calling any termination handlers named by calls to 
on exit. Normally, this is just the Standard I/O library function cleanup. Exit never returns. 

SEE ALSO 

exit(2), intro(3S), on_exit(3) 
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NAME 

frexp, ldexp, modf- floating point analysis and synthesis 
SYNOPSIS 

double frexp(value, eptr) 
double value; 
int *eptr; 

double Idexp(value, exp) 
double value; 
int exp; 

double modf( value, iptr) 
double value, *iptr; 

DESCRIPTION 

Frexp returns the significand of a double value as a double quantity, x, of magnitude less than 1 and stores 
an integer n, indirectly through eptr, such that value = x * 2 n . 

The results are not defined when value is an IEEE infinity or NaN. 

ldexp returns the quantity: 

value * 2 exp . 

modf returns the positive fractional part of value and stores the integer part indirectly through iptr. Thus the 
argument value and the returned values modf and *iptr would satisfy, in the absence of rounding error, 

(*iptr + modf) == value 

and 

0 <= modf < abslyalue). 

The results are not defined when value is an IEEE infinity or NaN. 

Note that the definition of modf varies among Unix implementations; avoid modf in portable code. 

SEE ALSO 

isinf(3) 
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NAME 

getenv - value for environment name 

SYNOPSIS 

char *getenv(name) 
char *name; 

DESCRIPTION 

Getenv searches the environment list (see environ^ 5)) for a string of the form name=value and returns a 
pointer to the string value if such a string is present, otherwise getenv returns the value 0 (NULL). 

SEE ALSO 

environ(5), execve(2) 
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NAME 

getfsent, getfsspec, getfsfile, getfstype, setfsent, endfsent - get file system descriptor file entry 
SYNOPSIS 

#include <fstab.h> 

struct fstab *getfsent() 

struct fstab *getfsspec(spec) 
char *spec; 

struct fstab *getfsfile(file) 
char *file; 

struct fstab *getfstype(type) 
char *type; 

int setfsent() 

int endfsent() 

DESCRIPTION 

These routines are included for compatibility with 4.2 BSD; they have been superseded by the 
getmntent(3) library routines. 

Getfsent, getfsspec, getfstype, and getfsfile each return a pointer to an object with the following structure 
containing the broken-out fields of a line in the file system description file, < fstab.h> . 

struct fstab{ 


char 

♦fsspec; 

char 

♦fsfile; 

char 

*fs_type; 

int 

fsfreq; 

int 

fs_passno; 


}; 

The fields have meanings described infstab(5). 

Getfsent reads the next line of the file, opening the file if necessary. 

Setfsent opens and rewinds the file. 

Endfsent closes the file. 

Getfsspec and getfsfile sequentially search from the beginning of the file until a matching special file name 
or file system file name is found, or until EOF is encountered. Getfstype does likewise, matching on the file 
system type field. 

FILES 

/etc/fstab 

SEE ALSO 

fstab(5) 

DIAGNOSTICS 

Null pointer (0) returned on EOF or error. 

BUGS 

The return value points to static information which is overwritten in each call. 
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NAME 

getgrent, getgrgid, getgmam, setgrent, endgrent- get group file entry 

SYNOPSIS 

#include <grp.h> 

struct group *getgrent() 

struct group *getgrgid(gid) 
int gid; 

struct group *getgrnam(name) 
char *name; 

setgrentO 

endgrentO 

DESCRIPTION 

Getgrent, getgrgid and getgmam each return pointers to an object with the following structure containing 
the broken-out fields of a line in the group file: 

struct group { 

char *gr_name; 

char *gr_passwd; 

int gr_gid; 

char **gr_mem; 

}; 

The members of this structure are: 

gr name The name of the group. 
gr_passwd The encrypted password of the group, 
gr gid The numerical group-ID. 

gr mem Null-terminated vector of pointers to the individual member names. 

Getgrent simply reads the next line while getgrgid and getgrnam search until a matching gid or name is 
found (or until EOF is encountered). Each routine picks up where the others leave off so successive calls 
may be used to search the entire file. 

A call to setgrent has the effect of rewinding the group file to allow repeated searches. Endgrent may be 
called to close the group file when processing is complete. 

FILES 

/etc/group 

/etc/yp/domm/mamWgroup.byname 

/etc/yp/dowwmname/group.bygid 

SEE ALSO 

getlogin(3), getpwent(3), group(5), ypserv(8) 

DIAGNOSTICS 

A null pointer (0) is returned on EOF or error. 

BUGS 

The return value points to static information which is overwritten on each call. 
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NAME 

getlogin - get login name 

SYNOPSIS 

char *getlogin() 

DESCRIPTION 

Getlogin returns a pointer to the login name as found in /etc/utmp. It may be used in conjunction with 
getpwnam to locate the correct password file entry when the same userid is shared by several login names. 

If getlogin is called within a process that is not attached to a typewriter, it returns NULL. The correct pro- 
cedure for determining the login name is to first call getlogin and if it fails, to call getpwuid(getuid()). 

FILES 

/etc/utmp 
SEE ALSO 

getpwent(3), getgrent(3), utmp(5) 

DIAGNOSTICS 

Returns NULL (0) if name not found. 

BUGS 

The return values point to static data whose content is overwritten by each call. 

Getlogin does not work for processes running under a pty (for example, emacs shell buffers, or shell tools) 
unless the program “fakes’ ’ the login name in the /etc/utmp file. 
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NAME 

setmntent, getmntent, addmntent, endmntent, hasmntopt - get file system descriptor file entry 

SYNOPSIS 

#include <stdio.h> 

^include <mntent.h> 

FILE *setmntent(filep, type) 
char * filep; 
char *type; 

struct mntent *getmntent(filep) 

FILE *filep; 

int addmntent(filep, mnt) 

FILE * filep; 
struct mntent *mnt; 

char *hasmntopt(mnt, opt) 
struct mntent *mnt; 
char *opt; 

int endmntent(filep) 

FILE * filep; 

DESCRIPTION 

These routines replace the getfsent routines for accessing the file system description file I etc! f stab. They 
are also used to access the mounted file system description file letclmtab. 

Setmntent opens a file system description file and returns a file pointer which can then be used with 
getmntent, addmntent, or endmntent. The type argument is the same as in fopen( 3). Getmntent reads the 
next line from filep and returns a pointer to an object with the following structure containing the broken-out 
fields of a line in the filesystem description file, <mntent.h>. The fields have meanings described in 
fstab(S). 

struct mntent { 

char *mnt_fsname; /* file system name */ 

char *mnt_dir; /* file system path prefix *1 

char *mnt_type; /* 4.2, nfs, swap, or xx */ 

char *mnt_opts; /* ro, quota, etc. */ 

int mnt_freq; /* dump frequency, in days */ 

int mnt_passno; /* pass number on parallel fsck */ 

}; 

Addmntent adds the mntent structure mnt to the end of the open file filep. Note that filep has to be opened 
for writing if this is to work. Hasmntopt scans the mnt_opts field of the mntent structure mnt for a substring 
that matches opt. It returns the address of the substring if a match is found, 0 otherwise. Endmntent closes 
the file. 

FILES 

/etc/fstab 

/etc/mtab 

SEE ALSO 

fstab(5), getfsent(3) 


DIAGNOSTICS 

Null pointer (0) returned on EOF or error. 
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BUGS 

The returned mntent structure points to static information that is overwritten in each call. 
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NAME 

getpass - read a password 
SYNOPSIS 

char *getpass(prompt) 
char ^prompt; 

DESCRIPTION 

Getpass reads a password from the file /dev/tty, or if that cannot be opened, from the standard input, after 
prompting with the null-terminated string prompt and disabling echoing. A pointer is returned to a null- 
terminated string of at most 8 characters. 

FILES 

/dev/tty 

SEE ALSO 

crypt(3) 

BUGS 

The return value points to static data whose content is overwritten by each call. 
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NAME 

getpw - get name from uid 

SYNOPSIS 

getpw(uid, buf) 
char *buf; 

DESCRIPTION 

Getpw is obsoleted by getpwent(3). 

Getpw searches the password file for the (numerical) uid, and fills in buf with the corresponding line; it 
returns non-zero if Mid could not be found. The line is null-terminated. 

FILES 

/etc/passwd 
SEE ALSO 

getpwent(3), passwd(5) 

DIAGNOSTICS 

Non-zero return on error. 
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NAME 

getpwent, getpwuid, getpwnam, setpwent, endpwent - get password file entry 
SYNOPSIS 

#include <pwd.h> 

struct passwd *getpwentO 

struct passwd *getpwuid(uid) 
int uid; 

struct passwd *getpwnam(name) 
char *name; 

int setpwentO 

int endpwentO 

DESCRIPTION 

Getpwent, getpwuid and getpwnam each return a pointer to an object with the following structure contain- 
ing the broken-out fields of a line in the password file. 

/* @(#)pwd.h 1.2 84/12/22 SMI; from UCB 4.1 83/05/03 */ 

struct passwd { I* see getpwent(3) *1 


char 

♦pwname; 

char 

*pw_passwd; 

int 

pwuid; 

int 

pwgid; 

int 

pwquota; 

char 

♦pwcomment; 

char 

*pw_gecos; 

char 

*pw_dir; 

char 

*pw_shell; 


}; 


struct passwd *getpwent(), *getpwuid(), *getpwnam(); 

The fields pw_quota and pw comment are unused; the others have meanings described in passwd( 5). 

Getpwent reads the next line (opening the file if necessary); setpwent rewinds the file; endpwent closes it. 

Getpwuid and getpwnam search from the beginning until a matching uid or name is found (or until EOF is 
encountered). 

FILES 

/etc/passwd 

/ etc/ ypl do main name Ipasswd.byndLme 
/etc/yp/domainname/passwd.byuid 

SEE ALSO 

getlogin(3), getgrent(3), passwd(5), ypserv(8) 

DIAGNOSTICS 

Null pointer (0) returned on EOF or error. 

BUGS 

The return value points to static information which is overwritten on each call. 
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NAME 

getwd - get current working directory pathname 
SYNOPSIS 

#include <sys/param.h> 

char *getwd(pathname) 

char pathname[MAXPATHLEN]; 

DESCRIPTION 

Getwd copies the absolute pathname of the current working directory to pathname and returns a pointer to 
the result. 

DIAGNOSTICS 

Getwd returns zero and places a message in pathname if an error occurs. 

BUGS 

Getwd may fail to return to the current directory if an error occurs. 
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NAME 

initgroups - initialize group access list 
SYNOPSIS 

initgroups(name, basegid) 
char *name; 
int basegid; 

DESCRIPTION 

Initgroups reads through the group file and sets up, using the setgroups( 2) call, the group access list for the 
user specified in name. The basegid is automatically included in the groups list. Typically this value is 
given as the group number from the password file. 

FILES 

/etc/group 

SEE ALSO 

setgroups(2) 

DIAGNOSTICS 

Initgroups returns -1 if it was not invoked by the super-user. 

BUGS 

Initgroups uses the routines based on getgrent( 3). If the invoking program uses any of these routines, the 
group structure will be overwritten in the call to initgroups. 
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NAME 

insque, remque - insert/remove element from a queue 

SYNOPSIS 

struct qelem { 

struct qelem *q_forw; 
struct qelem *q_back; 
char q_data[]; 


insque(elem, pred) 
struct qelem *elem, *pred; 

remque(elem) 
struct qelem *elem; 

DESCRIPTION 

Insque and remque manipulate queues built from doubly linked lists. Each element in the queue must be in 
the form of “struct qelem’’. Insque inserts elem in a queue imediately after pred.\ remque removes an 
entry elem from a queue. 

SEE ALSO 

“VAX Architecture Handbook”, pp. 228-235. It does work on Suns. 
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NAME 

isinf, isnan - test for indeterminate floating point values 

SYNOPSIS 

int isinf( value) 
double value; 

int isnan(value) 
double value; 

DESCRIPTION 

Isinf returns a value of 1 if its value is an IEEE format infinity (two words 0x7ff00000 0x00000000) or an 
IEEE negative infinity, and returns a zero otherwise. 

Isnan returns a value of 1 if its value is an IEEE format ‘not-a-number’ (two words 
0x7ff nnnnn Ox nnnnnnnn ) where n is not zero) or its negative, and returns a zero otherwise. 

Some library routines such as ecvt( 3) do not handle indeterminate floating point values gracefully. Pros- 
pective arguments to such routines should be checked with isinf or isnan before calling these routines. 

The FORTRAN Programmer' s Guide for the Sun Workstation describes in detail the format of TEF.E stan- 
dard floating point. 
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NAME 

malloc, free, realloc, calloc, cfree, memalign, valloc, alloca, malloc debug, malloc verify - memory allo- 
cator 

SYNOPSIS 

char * malloc (size) 
unsigned size; 

free(ptr) 
char *ptr; 

char *realloc(ptr, size) 
char *ptr; 
unsigned size; 

char *calIoc(neIem, elsize) 
unsigned nelem, elsize; 

cfree(ptr) 
char *ptr; 

char *memalign(alignment, size) 
unsigned alignment; 
unsigned size; 

char *valloc(size) 
unsigned size; 

char *alloca(size) 
int size; 

DESCRIPTION 

These routines provide a general-purpose memory allocation package. They maintain a table of free blocks 
for efficient allocation and coalescing of free storage. When there is no suitable space already free, the 
allocation routines call sbrk (see brk( 2)) to get more memoiy from the system. 

Each of the allocation routines returns a pointer to space suitably aligned for storage of any type of object. 
They return a null pointer if the request cannot be completed (see DIAGNOSTICS). 

Malloc returns a pointer to a block of at least size bytes beginning on a word boundary. A null (0) pointer is 
returned if size bytes of memory cannot be allocated. 

Free releases a previously allocated block. Its argument is a pointer to a block previously allocated by 
malloc, calloc, realloc, valloc, or memalign. 

malloc, calloc, realloc, valloc, or memalign. 

Realloc changes the size of the block referenced by ptr to size bytes and returns a pointer to the (possibly 
moved) block. The contents will be unchanged up to the lesser of the new and old sizes. For backwards 
compatibility, realloc accepts a pointer to a block freed since the most recent call to malloc, calloc, realloc, 
valloc, or memalign. Note that using realloc with a block freed before the most recent call to malloc, cal- 
loc, realloc, valloc, or memalign is an error. 

Calloc uses malloc to allocate space for an array of nelem elements of size elsize, initializes the space to 
zeros, and returns a pointer to the initialized block. The block can be freed with free or cfree. 

Memalign allocates size bytes on a specified alignment boundary, and returns a pointer to the allocated 
block. The value of the returned address is guaranteed to be an even multiple of alignment. Note that the 
value of alignment must be a power of two, and must be greater than or equal to the size of a word. 

Valloc (size) is equivalent to memalign(getpagesize(), size). 
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Alloca allocates size bytes of space in the stack frame of the caller, and returns a pointer to the allocated 
block. This temporary space is automatically freed when the caller returns. 

SEE ALSO 

“Fast Fits” by C. J. Stephenson, in Proceedings of the ACM 9th Symposium on Operating Systems, 
SIGOPS Operating Systems Review, vol. 17, no. 5, October 1983. 

Core Wars, in Scientific American, May 1984. 

DIAGNOSTICS 

Malloc, calloc, realloc, valloc, and memalign return a null pointer (0) and set errno if arguments are 
invalid, or if there is insufficient available memory, or if the heap has been detectably corrupted, e.g. by 
storing outside the bounds of a block. 

More detailed diagnostics can be made available to programs using malloc, calloc, realloc, valloc, 
memalign, cfree, and free, by including a special relocatable object file at link time (see FILES). This file 
also provides routines for control of error handling and diagnosis, as defined below. Note that these rou- 
tines are not defined in the standard library. 

int malloc_debug(level) 
int level; 

int ma!loc_verify() 

Malloc_debug sets the level of error diagnosis and reporting during subsequent calls to malloc, calloc, 
realloc, valloc, memalign, cfree, and free. The value of level is interpreted as follows: 

[Level 0] Malloc, calloc, realloc, valloc, memalign, cfree, and free behave the same as in the stan- 

dard library. 

[Level 1] Malloc, calloc, realloc, valloc, memalign, cfree, and free abort with a message to stderr 

if errors are detected in arguments or in the heap. If a bad block is encountered, its 
address and size are included in the message. 

[Level 2] Same as level 1, except that the entire heap is examined on every call to malloc, calloc, 

realloc, valloc, memalign, cfree, and free. 

Malloc debug returns the previous error diagnostic level. The default level is 1. 

Malloc_verify attempts to determine if the heap has been corrupted. It scans all blocks in the heap (both 
free and allocated) looking for strange addresses or absurd sizes, and also checks for inconsistencies in the 
free space table. Malloc verify returns 1 if all checks pass without error, and otherwise returns 0. The 
checks can take a significant amount of time, so it should not be used indiscriminately. 

ERRORS 

Malloc, calloc, realloc, valloc, memalign, cfree, and free will set errno if: 

[EINVAL] An invalid argument was given. The value of ptr given to free, cfree, or realloc must be 
a pointer to a block previously allocated by malloc, calloc, realloc, valloc, or memalign. 
The EINVAL condition also occurs if the heap is found to have been corrupted. More 
detailed information may be obtained by enabling range checks using malloc_debug. 

[ENOMEM] size bytes of memory could not be allocated. 

FILES 

/usr/lib/debug/malloc.o diagnostic versions of malloc, free, etc. 

BUGS 

Alloca is both machine- and compiler-dependent; its use is discouraged. 

Since realloc accepts a pointer to a block freed since the last call to malloc, calloc, realloc, valloc, or 
memalign, a degradation of performance results. The semantics of free should be changed so that the con- 
tents of a previously freed block are undefined. 


Sun Release 3.0 


Last change: 15 November 1984 


163 



MKTEMP(3) 


C LIBRARY FUNCTIONS 


MKTEMP ( 3 ) 


NAME 

mktemp - make a unique file name 
SYNOPSIS 

char *mktemp(template) 
char ^template; 

DESCRIPTION 

Mktemp replaces template by a unique file name, and returns the address of the template. The template 
should look like a file name with six trailing X’s, which will be replaced with the current process id and a 
unique letter. 

Notes: 

• Mktemp actually changes the template string which you pass, this means that you cannot use the same 
template string more than once — you need a fresh template for every unique file you want to open. 

• When mktemp is creating a new unique filename it checks for the prior existence of a file with that name. 
This means that if you are creating more than one unique filename, it is bad practice to use the same root 
template for multiple invocations of mktemp. 

SEE ALSO 

getpid(2) 
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NAME 

monitor, monstartup, moncontrol - prepare execution profile 
SYNOPSIS 

monitor(lowpc, highpc, buffer, bufsize, nfunc) 
int (*Iowpc)(), (*highpc)(); 
short buffer[]; 

monstartup(Iowpc, highpc) 
int (*lowpc)(), (*highpc)(); 

moncontrol(mode) 

DESCRIPTION 

There are two different forms of monitoring available: An executable program created by: 
cc -p . . . 

automatically includes calls for the prof(l) monitor and includes an initial call to its start-up routine mon- 
startup with default parameters; monitor need not be called explicitly except to gain fine control over profil 
buffer allocation. An executable program created by: 

cc -pg . . . 

automatically includes calls for the gprofi 1) monitor. 

Monstartup is a high level interface to profil(2). Lowpc and highpc specify the address range that is to be 
sampled; the lowest address sampled is that of lowpc and the highest is just below highpc. Monstartup 
allocates space using sbrk( 2) and passes it to monitor (see below) to record a histogram of periodically 
sampled values of the program counter, and of counts of calls of certain functions, in the buffer. Only calls 
of functions compiled with the profiling option -p of cc(l) are recorded. 

To profile the entire program, it is sufficient to use 

extern etext(); 

monstartup(0x8000, etext); 

Etext lies just above all the program text, see end( 3). 

To stop execution monitoring and write the results on the file mon.out, use 
monitor(O); 

then profil) can be used to examine the results. 

Moncontrol is used to selectively control profiling within a program. This works with either profil) or 
gprofi 1) type profiling. When the program starts, profiling begins. To stop the collection of histogram 
ticks and call counts use moncontrol (0); to resume the collection of histogram ticks and call counts use 
moncontrol (1). This allows the cost of particular operations to be measured. Note that an output file will 
be produced upon program exit irregardless of the state of moncontrol. 

Monitor is a low level interface to profil (2). Lowpc and highpc are the addresses of two functions; buffer is 
the address of a (user supplied) array of bufsize short integers. At most nfunc call counts can be kept. For 
the results to be significant, especially where there are small, heavily used routines, it is suggested that the 
buffer be no more than a few times smaller than the range of locations sampled. Monitor divides the buffer 
into space to record the histogram of program counter samples over the range lowpc to highpc, and space 
to record call counts of functions compiled with the -p option to cc(l). 

To profile the entire program, it is sufficient to use 
extern etext(); 

monitor(0x8000, etext, buf, bufsize, nfunc); 
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FILES 

mon.out 
SEE ALSO 

cc(l), prof(l), gprof(l), profil(2), sbrk(2) 
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NAME 

nlist - get entries from name list 

SYNOPSIS 

#include <nlist.h> 

nlist(filename, nl) 
char * filename; 
struct nlist nl[]; 

DESCRIPTION 

Nlist examines the name list in the given executable output file and selectively extracts a list of values. The 
name list consists of an array of structures containing names, types and values. The list is terminated with 
a null name. Each name is looked up in the name list of the file. If the name is found, the type and value 
of the name are inserted in the next two fields. If the name is not found, both entries are set to 0. See 
a.out(5) for the structure declaration. 

This subroutine is useful for examining the system name list kept in the file /vmunix. In this way programs 
can obtain system addresses that are up to date. 

SEE ALSO 

a.out(5) 

DIAGNOSTICS 

All type entries are set to 0 if the file cannot be found or if it is not a valid namelist 


Sun Release 3.0 


Last change; 19 January 1983 


167 



ONJEXIT ( 3 ) 


C LIBRARY FUNCTIONS 


ONEXIT ( 3 ) 


NAME 

onexit - name termination handler 
SYNOPSIS 

int on_exit(procp, arg) 
void (*procp)(); 
caddr_t arg; 

DESCRIPTION 

On exit names a routine to be called after a program calls exit (3) or returns normally, and before its pro- 
cess terminates. The routine named is called as 
(*procp)(status, arg); 

where status is the argument with which exit was called, or zero if main returns. Typically, arg is the 
address of an argument vector to (*procp), but may be an integer value. Several calls may be made to 
on exit, specifying several termination handlers. The order in which they are called is the reverse of that in 
which they were given to on exit. 

SEE ALSO 

exit(3) 

DIAGNOSTICS 

On exit returns zero normally, or nonzero if the procedure name could not be stored. 

BUGS 

Currently there is a limit of 20 termination handlers, including any invoked implicitly (for example, by 
8P ro f( 1) or tcov( 1) processing). Calls to on exit beyond this number will fail 

NOTES 

This call is specific to Sun Unix and should not be used if portability is a concern. 

Standard I/O exit processing is always done last 
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NAME 

perror, sys_errlist, sys nerr, ermo - system error messages 

SYNOPSIS 

perror(s) 
char *s; 

int sysnerr; 
char *sys_errlist[]; 

int errno; 

DESCRIPTION 

Perror produces a short error message on the standard error file describing the last error encountered dur- 
ing a call to the system from a C program. First the argument string s is printed, then a colon, then the 
message and a new-line. Most usefully, the argument string is the name of the program which incurred the 
error. The error number is taken from the external variable errno (see intro (2)), which is set when errors 
occur but not cleared when non-erroneous calls are made. 

To simplify variant formatting of messages, the vector of message strings sys errlist is provided; errno can 
be used as an index in this table to get the message string without the newline. Sys nerr is the number of 
messages provided for in the table; it should be checked because new error codes may be added to the sys- 
tem before they are added to the table. 

SEE ALSO 

intro(2), psignal(3) 
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NAME 

psignal, sys_siglist - system signal messages 
SYNOPSIS 

psignal(sig, s) 
unsigned sig; 
char *s; 

char *sys_siglist[]; 

DESCRIPTION 

Psignal produces a short message on the standard error file describing the indicated signal. First the argu- 
ment string s is printed, then a colon, then the name of the signal and a new-line. Most usefully, the argu- 
ment string is the name of the program which incurred the signal. The signal number should be from 
among those found in <signal.h>. 

To simplify variant formatting of signal names, the vector of message strings sysjsiglist is provided; the 
signal number can be used as an index in this table to get the signal name without the newline. The define 
NSIG defined in <signal.h> is the number of messages provided for in the table; it should be checked 
because new signals may be added to the system before they are added to the table. 

SEE ALSO 

perror(3), signal(3) 
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NAME 

qsort - quicker sort 
SYNOPSIS 

qsort(base, nel, width, compar) 
char *base; 
int (*compar)(); 

DESCRIPTION 

Qsort is an implementation of the quicker-sort algorithm. The first argument is a pointer to the base of the 
data; the second is the number of elements; the third is the width of an element in bytes; the last is the name 
of the comparison routine to be called with two arguments which are pointers to the elements being com- 
pared. The routine must return an integer less than, equal to, or greater than 0 according as the first argu- 
ment is to be considered less than, equal to, or greater than the second. 

SEE ALSO 

sort(l) 
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NAME 

random, srandom, initstate, setstate — better random number generator; routines for changing generators 
SYNOPSIS 

long random() 

srandom(seed) 
int seed; 

long *initstate(seed, state, n) 
unsigned seed; 
long *state; 
intn; 

long *setstate(state) 
long *state; 

DESCRIPTION 

Random uses a non-linear additive feedback random number generator employing a default table of size 31 
long integers to return successive pseudo-random numbers in the range from 0 to 2 3I -1. The period of this 
random number generator is very large, approximately 16*(2 31 -1). 

Random! srandom have (almost) the same calling sequence and initialization properties as randlsrand. The 
difference is that rand( 3C) produces a much less random sequence ~ in fact, the low dozen bits generated 
by rand go through a cyclic pattern. All the bits generated by random are usable. For example, “ran- 
dom()&01” will produce a random binary value. 

Unlike srand, srandom does not return the old seed; the reason for this is that the amount of state informa- 
tion used is much more than a single word. (Two other routines are provided to deal with 
restarting/changing random number generators). Like rand( 3C), however, random will by default produce 
a sequence of numbers that can be duplicated by calling srandom with 1 as the seed. 

The initstate routine allows a state array, passed in as an argument, to be initialized for future use. The size 
of the state array (in bytes) is used by initstate to decide how sophisticated a random number generator it 
should use -- the more state, the better the random numbers will be. (Current "optimal" values for the 
amount of state information are 8, 32, 64, 128, and 256 bytes; other amounts will be rounded down to the 
nearest known amount. Using less than 8 bytes will cause an error). The seed for the initialization (which 
specifies a starting point for the random number sequence, and provides for restarting at the same point) is 
also an argument. Initstate returns a pointer to the previous state information array. 

Once a state has been initialized, the setstate routine provides for rapid switching between states. Setstate 
returns a pointer to the previous state array; its argument state array is used for further random number gen- 
eration until the next call to initstate or setstate. 

Once a state array has been initialized, it may be restarted at a different point either by calling initstate 
(with the desired seed, the state array, and its size) or by calling both setstate (with the state array) and 
srandom (with the desired seed). The advantage of calling both setstate and srandom is that the size of the 
state array does not have to be remembered after it is initialized. 

With 256 bytes of state information, the period of the random number generator is greater than 2 69 , which 
should be sufficient for most purposes. 

DIAGNOSTICS 

If initstate is called with less than 8 bytes of state information, or if setstate detects that the state informa- 
tion has been garbled, error messages are printed on the standard error output. 

SEE ALSO 

rand(3C) 

BUGS 

About 2/3 the speed of rand( 3C). 
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NAME 

re comp, reexec - regular expression handler 

SYNOPSIS 

char *re_comp(s) 
char *s; 

re_exec(s) 
char *s; 

DESCRIPTION 

Re comp compiles a string into an internal form suitable for pattern matching. Re exec checks the argu- 
ment string against the last string passed to re_comp. 

Re comp returns 0 if the string s was compiled successfully; otherwise a string containing an error message 
is returned. If re_comp is passed 0 or a null string, it returns without changing the currently compiled regu- 
lar expression. 

Re exec returns 1 if the string s matches the last compiled regular expression, 0 if the string s failed to 
match the last compiled regular expression, and -1 if the compiled regular expression was invalid (indicat- 
ing an internal error). 

The strings passed to both re comp and re exec may have trailing or embedded newline characters; they 
are terminated by nulls. The regular expressions recognized are described in the manual entry for ed( 1), 
given the above difference. 

SEE ALSO 

ed(l), ex(l), egrep(l), fgrep(l), grep(l) 

DIAGNOSTICS 

Re exec returns -1 for an internal error. 

Re comp returns one of the following strings if an error occurs: 

No previous regular expression 
Regular expression too long 
unmatched \( 
missing ] 

too many \(\) pairs 
unmatched \) 
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NAME 

scandir, alphasort- scan a directory 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/dir.h> 

scandir(dirname, namelist, select, compar) 

char *dirname; 

struct direct *(*namelist[ ]); 

int (*select)(); 

int (*compar)(); 

alphasort(dl, d2) 
struct direct **dl, **d2; 

DESCRIPTION 

Scandir reads the directory dirname and builds an array of pointers to directory entries using malloc( 3). 
The second parameter is a pointer to an array of structure pointers. The third parameter is a pointer to a 
routine which is called with a pointer to a directory entry and should return a non zero value if the directory 
entry should be included in the array. If this pointer is null, then all the directory entries will be included. 
The last argument is a pointer to a routine which is passed to qsort(i) to sort the completed array. If this 
pointer is null, the array is not sorted. Alphasort is a routine which will sort the array alphabetically. 

Scandir returns the number of entries in the array and a pointer to the array through the parameter namelist. 
SEE ALSO 

directory(3), malloc(3), qsort(3) 

DIAGNOSTICS 

Returns -1 if the directory cannot be opened for reading or if mallocO) cannot allocate enough memory to 
hold all the data structures. 
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NAME 

setjmp, longjmp - non-local goto 

SYNOPSIS 

#include <setjmp.h> 

val = setjmp(env) 
jmp_buf env; 

longjmp(env, val) 
jmpbuf env; 

val = _setjmp(env) 
jmp buf env; 

_longjmp(env, val) 
jmp buf env; 

DESCRIPTION 

Setjmp and longjmp are useful for dealing with errors and interrupts encountered in a low-level subroutine 
of a program. 

Setjmp saves its stack environment in env for later use by longjmp. Setjmp also saves the register environ- 
ment Setjmp returns the value 0. If a longjmp call will be made, the routine which called setjmp should 
not return until after the longjmp has returned control (see below). 

Longjmp restores the environment saved by the last call of setjmp, and then returns in such a way that exe- 
cution continues as if the call of setjmp had just returned the value val to the function that invoked setjmp. 
The calling function must not itself have returned in the interim, otherwise longjmp will be returning con- 
trol to a possibly non-existent environment All memory-bound data have values as of the time longjmp 
was called. The machine registers are restored to the values they had at the time that setjmp was called. 
But because the register storage class is only a hint to the C compiler, variables declared as register vari- 
ables may not necessarily be assigned to machine registers, so their values are unpredictable after a 
longjmp. This is especially a problem for programmers trying to write machine-independent C routines. 

The following code fragment indicates the flow of control of the setjmp and longjmp combination: 

. . .function declaration 

jmpbuf myenvironment; 

. . . code . . . 

if ( setjmp ( my_environment ) ) { 

this is the code after the return from longjmp 
. . . more code 

register variables have unpredictable values 
. . . more code 

} else { 

this is the return from setjmp 

. . . more code 

Do not modify register variables 
in this leg of the code 
. . . more code 

} 

Setjmp and longjmp save and restore the signal mask sigsetmask(2), while _setjmp and longjmp manipu- 
late only the C stack and registers. 

SEE ALSO 

sigsetmask(2), sigvec(2), signal(3) 
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BUGS 

Setjmp does not save current notion of whether the process is executing on the signal stack. The result is 
that a longjmp to some place on the signal stack leaves the signal stack state incorrect. 
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NAME 

setuid, seteuid, setruid, setgid, setegid, setrgid- set user and group ID 

SYNOPSIS 

setuid(uid) 

seteuid(euid) 

setruid(ruid) 

setgid(gid) 

setegid(egid) 

setrgid(rgid) 

DESCRIPTION 

Setuid ( setgid ) sets both the real and effective user ED (group ED) of the current process to as specified. 
Seteuid ( setegid ) sets the effective user ID (group ID) of the current process. 

Setruid (setruid) sets the real user ID (group ID) of the current process. 

These calls are only permitted to the super-user or if the argument is the real or effective ED. 

SEE ALSO 

setreuid(2), setregid(2), getuid(2), getgid(2) 

DIAGNOSTICS 

Zero is returned if the user (group) ID is set; -1 is returned otherwise, with the global variable errno set as 
for setreuid or setregid. 
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NAME 

signal - simplified software signal facilities 

SYNOPSIS 

#include <signal.h> 

(*signal(sig, fnnc))() 
void (*func)(); 

DESCRIPTION 

Signal is a simplified interface to the more general sigvec(2) facility. Programs that use signal in prefer- 
ence to sigvec are more likely to be portable to all UNIX systems. 

A signal is generated by some abnormal event, initiated by a user at a terminal (quit, interrupt, stop), by a 
program error (bus error, etc.), by request of another program (kill), or when a process is stopped because it 
wishes to access its control terminal while in the background (see try (4)). Signals are optionally generated 
when a process resumes after being stopped, when the status of child processes changes, or when input is 
ready at the control terminal. Most signals cause termination of the receiving process if no action is taken; 
some signals instead cause the process receiving them to be stopped, or are simply discarded if the process 
has not requested otherwise. Except for the SIGKILL and SIGSTOP signals, the signal call allows signals 
either to be ignored or to cause an interrupt to a specified location. The following is a list of all signals 
with names as in the include file <signal.h > : 


SIGHUP 

1 

hangup 

SIGINT 

2 

interrupt 

SIGQUIT 

3* 

quit 

SIGILL 

4* 

illegal instruction (other than A-line or F-line op code) 

SIGTRAP 

5* 

trace trap 

SIGIOT 

6* 

IOT instruction (not generated on Suns) 

SIGEMT 

7* 

EMT instruction (A-Une or F-line op code) 

SIGFPE 

8* 

floating point exception 

SIGKILL 

9 

kill (cannot be caught, blocked, or ignored) 

SIGBUS 

10* 

bus error 

SIGSEGV 

11* 

segmentation violation 

SIGSYS 

12* 

bad argument to system call 

SIGPIPE 

13 

write on a pipe with no one to read it 

SIGALRM 

14 

alarm clock 

SIGTERM 

15 

software termination signal 

SIGURG 

16 

urgent condition present on socket 

SIGSTOP 

17t 

stop (cannot be caught, blocked, or ignored) 

SIGTSTP 

18t 

stop signal generated from keyboard 

SIGCONT 

19. 

continue after stop (cannot be blocked) 

SIGCHLD 

20* 

child status has changed 

SIGTTIN 

21f 

background read attempted from control terminal 

SIGTTOU 

22t 

background write attempted to control terminal 

SIGIO 

23 

i/o is possible on a descriptor (see fcntl{ 2)) 

SIGXCPU 

24 

cpu time limit exceeded (see setrlimit( 2)) 

SIGXFSZ 

25 

file size limit exceeded (see setrlimit(2)) 

SIGVTALRM 26 

virtual time alarm (see setitimer{ 2)) 

SIGPROF 

27 

profiling timer alarm (see setitimer( 2)) 

SIGWINCH 

28* 

window changed (see win(4S)) 


The starred signals in the list above cause a core image if not caught or ignored. 

If func is SIG DFL, the default action for signal sig is reinstated; this default is termination (with a core 
image for starred signals) except for signals marked with • or t. Signals marked with • are discarded if the 
action is SIG_DFL; signals marked with t cause the process to stop. If func is SIGIGN the signal is sub- 
sequently ignored and pending instances of the signal are discarded. Otherwise, when the signal occurs 
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further occurences of the signal are automatically blocked and func is called. 

A return from the function unblocks the handled signal and continues the process at the point it was inter- 
rupted. Unlike previous signal facilities, the handler func remains installed after a signal has been 
delivered. 

If a caught signal occurs during certain system calls, causing the call to terminate prematurely, the call is 
automatically restarted. In particular this can occur during a read or write (2) on a slow device (such as a 
terminal; but not a file) and during a wait(2). 

The value of signal is the previous (or initial) value of func for the particular signal. 

After a fork (2) or vfork(2) the child inherits all signals. An execve (2) resets all caught signals to the 
default action; ignored signals remain ignored. 

NOTES 

The handler routine can be declared: 

handler(sig, code, scp) 
int sig, code; 
struct sigcontext *scp; 

Here sig is the signal number. Code is a parameter of certain signals that provides additional detail. Scp is 
a pointer to the sigcontext structure (defined in <signal.h>), used to restore the context from before the sig- 
nal. 


CODES 

The following defines the codes for signals which produce them. All of these symbols are defined in 
<signal.h > : 


Hardware condition 

Signal 

Code 

Illegal instruction 

SIGILL 

ILL INSTR FAULT 

Privilege violation 

SIGILL 

ILL PRIVVIO FAULT 

Coprocessor protocol error 

SIGILL 

ELL INSTR FAULT 

Trap #n (1 <= n <= 14) 

~ n’ s above should be italicized 

SIGILL 

ILLTRAPnFAULT 

A-line op code 

SIGEMT 

EMT EMU1010 

F-line op code 

SIGEMT 

EMTEMUllll 

Integer division by zero 

SIGFPE 

FPE INTDIV TRAP 

CHK or CHK2 instruction 

SIGFPE 

FPE CHKINST TRAP 

TRAPV or TRAPcc or cpTRAPcc 

SIGFPE 

FPE TRAPV TRAP 

IEEE floating point compare unordered 

SIGFPE 

FPE FLTBSUN TRAP 

IEEE floating point inexact 

SIGFPE 

FPE_FLTINEX_TRAP 

IEEE floating point division by zero 

SIGFPE 

FPEFLTDI VTR AP 

IEEE floating point underflow 

SIGFPE 

FPE_FLTUND_TRAP 

IEEE floating point operand error 

SIGFPE 

FPE FLTOPERR TRAP 

IEEE floating point overflow 

SIGFPE 

FPE FLTOVF FAULT 

IEEE floating point signaling NaN 

SIGFPE 

FPE FLTNAN TRAP 


RETURN VALUE 

The previous action is returned on a successful call. Otherwise, -1 is returned and errno is set to indicate 
the error. 

ERRORS 

Signal will fail and no action will take place if one of the following occur: 

[EINVAL] Sig is not a valid signal number. 
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[EINVAL] An attempt is made to ignore or supply a handler for SIGKILL or SIGSTOP. 

[EINVAL] An attempt is made to ignore SIGCONT (by default SIGCONT is ignored). 

SEE ALSO 

kill(l), ptrace(2), kill(2), sigvec(2), sigblock(2), sigsetmask(2), sigpause(2), sigstack(2), setjmp(3), tty(4) 
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NAME 

sleep - suspend execution for interval 

SYNOPSIS 

sleep(seconds) 
unsigned seconds; 

DESCRIPTION 

Sleep suspends the current process from execution for the number of seconds specified by the argument. 
The actual suspension time may be up to 1 second less than that requested, because scheduled wakeups 
occur at fixed 1-second intervals, and may be an arbitrary amount longer because of other activity in the 
system. 

Sleep is implemented by setting an interval timer and pausing until it expires. The previous state of this 
timer is saved and restored. If the sleep time exceeds the time to the expiration of the previous value of the 
timer, the process sleeps only until the timer would have expired, and the signal which occurs with the 
expiration of the timer is sent one second later. 

SEE ALSO 

setitimer(2), sigpause(2) 

BUGS 

An interface with finer resolution is needed. 


Sun Release 3.0 


Last change: 13 June 1983 


181 



STRING ( 3 ) 


C LIBRARY FUNCTIONS 


STRING (3) 


NAME 

string strcat, stmcat, strcmp, stmcmp, strcpy, stmcpy, strlen, index, rindex - string operations 
SYNOPSIS 

#include <strings.h> 

char *strcat(sl, s2) 
char *sl, *s2; 

char *strncat(sl, s2, n) 
char *sl, *s2; 

strcmp(sl, s2) 
char *sl, *s2; 

strncmp(sl, s2, n) 
char *sl, *s2; 

char *strcpy(sl, s2) 
char *sl, *s2; 

char *strncpy(sl, s2, n) 
char *sl, *s2; 

strlen(s) 
char *s; 

char *index(s, c) 
char *s, c; 

char *rindex(s, c) 
char *s, c; 

DESCRIPTION 

These functions operate on null-terminated strings. They do not check for overflow of any receiving string. 

Strcat appends a copy of string s2 to the end of string si . Strncat copies at most n characters. Both return 
a pointer to the null-terminated result. 

Strcmp compares its arguments and returns an integer greater than, equal to, or less than 0, according as si 
is lexicographically greater than, equal to, or less than s2. Strncmp makes the same comparison but looks 
at at most n characters. 

Strcpy copies string s2 to si, stopping after the null character has been moved. Strncpy copies exactly n 
characters, truncating or null-padding s2; the target may not be null-terminated if the length of s2 is n or 
more. Both return si . 

Strlen returns the number of non-null characters in s. 

Index ( rindex ) returns a pointer to the first (last) occurrence of character c in string s, or zero if c does not 
occur in the string. 

BUGS 

Strcmp uses native character comparison, which is signed on the Sun. 

On the Sun processor (and on some other machines), you can NOT use a zero pointer to indicate a null 
string. A zero pointer is an error and results in an abort of the program. If you wish to indicate a null 
string, you must have a pointer that points to an explicit null string. On PDP-ll’s and VAX’en, a source 
pointer of zero (0) can generally be used to indicate a null string. Programmers using NULL to represent 
an empty string should be aware of this portability issue. 
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NAME 

swab - swap bytes 
SYNOPSIS 

swab(from, to, nbytes) 
char *from, *to; 

DESCRIPTION 

Swab copies nbytes bytes pointed to by from to the position pointed to by to, exchanging adjacent even and 
odd bytes. It is useful for carrying binary data between high-ender machines (IBM 360’s, MC68000’s, etc) 
and low-ender machines (PDP-ll’s and VAX’es). 

Nbytes should be even. 

The from and to addresses should not overlap in portable programs. 
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NAME 

syslog, openlog, closelog - control system log 

SYNOPSIS 

#include <syslog.h> 

openlog(ident, logstat) 
char *ident; 

syslog(priority, message, parameters ... ) 
char ^message; 

closelogO 

DESCRIPTION 

Syslog arranges to write the message onto the system log maintained by syslog (8). The message is tagged 
with priority. The message looks like a printfQS) string except that %m is replaced by the current error 
message (collected from errno). A trailing newline is added if needed. This message will be read by sys- 
log (8) and output to the system console or files as appropriate. 

If special processing is needed, openlog can be called to initialize the log file. Parameters are i dent which 
is prepended to every message, and logstat which is a bit field indicating special status; current values are: 

LOGPID log the process id with each message: useful for identifying instantiations of daemons. 

Openlog returns zero on success. If syslog cannot send datagrams to syslog(8), then it writes on 
/dev/ console instead. If /dev /console cannot be written, standard error is used. In either case, it returns -1. 

Closelog can be used to close the log file. It is automatically closed on a successful exec system call (see 
execve(2)). 

EXAMPLES 

syslog(LOG_SALERT, "who: internal error 23"); 
openlog(" serverftp" , LOG PID); 

syslog(LOG_INFO, "Connection from host %d", CallingHost); 

SEE ALSO 

syslog(8) 
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NAME 

system - issue a shell command 

SYNOPSIS 

system(string) 
char ^string; 

DESCRIPTION 

System causes the string to be given to sh(l) as input as if the string had been typed as a command at a ter- 
minal. The current process waits until the shell has completed, then returns the exit status of the shell. 

SEE ALSO 

popen(3S), execve(2), wait(2) 

DIAGNOSTICS 

Exit status 127 (may be displayed as "32512") indicates the shell couldn’t be executed. 
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NAME 

ttyname, isatty, ttyslot - find name of a terminal 
SYNOPSIS 

char *ttyname(filedes) 
isatty(filedes) 
ttyslotO 
DESCRIPTION 

Ttyname returns a pointer to the null-terminated path name of the terminal device associated with file 
descriptor filedes. 

Isatty returns 1 if filedes is associated with a terminal device, 0 otherwise. 

Ttyslot returns the number of the entry in the ttys (5) file for the control terminal of the current process. 

FILES 

/dev/* 

/etc/ttys 

SEE ALSO 

ioctl(2), ttys(5) 

DIAGNOSTICS 

Ttyname returns a null pointer (0) if filedes does not describe a terminal device in directory ‘/dev’. 

Ttyslot returns 0 if ‘/etc/ttys’ is inaccessible or if it cannot determine the control terminal. 

BUGS 

The return value points to static data whose content is overwritten by each call. 
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NAME 

varargs - variable argument list 
SYNOPSIS 

#include <varargs.h> 

/«/icft'on(va_aIist) 

vadcl 

va_list pvar; 

va_start(pvar); 

f = va_arg (pvar, type); 

va_emd (pvar); 

DESCRIPTION 

This set of macros provides a means of writing portable procedures that accept variable argument lists. 
Routines having variable argument lists (such as printf( 3S)) that do not use varargs are inherently nonport- 
able, since different machines use different argument passing conventions. 

va_alist is used in a function header to declare a variable argument list. 

va_dcl is a declaration for va_alist. Note that there is no semicolon after va_dcl. 

va_Iist is a type which can be used for the variable pvar, which is used to traverse the list. One such vari- 
able must always be declared. 

va_start(pvar) is called to initialize pvar to the beginning of the list. 

va_arg(pvar, type) will return the next argument in the list pointed to by pvar. Type is the type the argu- 
ment is expected to be. Different types can be mixed, but it is up to the routine to know what type of argu- 
ment is expected, since it cannot be determined at runtime. 

va_end(pvar) is used to finish up. 

Multiple traversals, each bracketed by va_start ... va_end, are possible. 

EXAMPLE 

#include <varargs.h> 
execl(va_alist) 
va_dcl 
{ ~ 

va_list ap; 
char *file; 
char *args[100]; 
int argno = 0; 


va_start(ap); 

file = va_arg(ap, char *); 

while (args[argno++] = va_arg(ap, char *)) 

9 

va_end(ap); 

return execv(file, args); 


BUGS 

It is up to the calling routine to determine how many arguments there are, since it is not possible to deter- 
mine this from the stack frame. For example, execl passes a 0 to signal the end of the list. Printf can tell 
how many arguments are supposed to be there by the format. 

Do not use types that are less than 1 word in size. 
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NAME 

intro - introduction to compatibility library functions 
DESCRIPTION 

These functions constitute the compatibility library portion of libc. They are automatically loaded as 
needed by the C compiler cc(l). The link editor searches this library under the “-lc” option. Use of these 
routines (instead of newer equivalent routines) is encouraged for the sake of program portability. Manual 
entries for the functions in this library describe the proper routine to use. 

LIST OF FUNCTIONS 


Name 

Appears on Page Description 

alarm 

alarm.3c 

schedule signal after specified time 

ftime 

time.3c 

get date and time 

getopt 

getopt.3c 

get option letter from argv 

gtty 

stty.3c 

set and get terminal state 

nice 

nice.3c 

set program priority 

optarg 

getopt.3c 

get option letter from argv 

optind 

getopt.3c 

get option letter from argv 

pause 

pause.3c 

stop until signal 

rand 

rand.3c 

random number generator 

srand 

rand.3c 

random number generator 

stty 

stty ,3c 

set and get terminal state 

time 

time.3c 

get date and time 

times 

times. 3c 

get process times 

tmpnam 

tmpnam.3c 

create a name for a temporary file 

ulimit 

ulimit.3c 

get and set user limits 

utime 

utime.3c 

set file times 

vlimit 

vlimit.3c 

control maximum system resource consumption 

vtimes 

vtimes.3c 

get information about resource utilization 
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NAME 

alarm - schedule signal after specified time 

SYNOPSIS 

alarm(seconds) 
unsigned seconds; 

DESCRIPTION 

Alarm causes signal SIGALRM, see sigvec (2), to be sent to the invoking process in a number of seconds 
given by the argument. Unless caught or ignored, the signal terminates the process. 

Alarm requests are not stacked; successive calls reset the alarm clock. If the argument is 0, any alarm 
request is canceled. Because of scheduling delays, resumption of execution of when the signal is caught 
may be delayed an arbitrary amount. The longest specifiable delay time is 2147483647 seconds. 

The return value is the amount of time previously remaining in the alarm clock. 

SEE ALSO 

sigpause(2), sigvec(2), signal(3), sleep(3) 
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NAME 

getopt, optarg, optind - get option letter from argv 
SYNOPSIS 

int getopt(argc, argv, optstring) 
int args; 
char **argv; 
char *optstring; 

extern char *optarg; 
extern int optind; 

DESCRIPTION 

This routine is included for compatibility with UNIX System V. 

Getopt returns the next option letter in argv that matches a letter in optstring. Optstring is a string of recog- 
nized option letters; if a letter is followed by a colon, the option is expected to have an argument that may 
or may not be separated from it by white space. Optarg is set to point to the start of the option argument on 
return from getopt. 

Getopt places in optind the argv index of the next argument to be processed. Because optind is external, it 
is normally initialized to zero automatically before the first call to getopt. 

When all options have been processed (i.e., up to the first non-option argument), getopt returns EOF. The 
special option may be used to delimit the end of the options; EOF will be returned, and — will be 
skipped. 

DIAGNOSTICS 

Getopt prints an error message on stderr and returns a question mark (?) when it encounters an option 
letter not included in optstring. 

EXAMPLE 

The following code fragment shows how one might process the arguments for a command that can take the 
mutually exclusive options a and b, and the options f and o, both of which require arguments: 

main(argc, argv) 
int argc; 
char **argv; 

{ 

intc; 

extern int optind; 
extern char * optarg; 


while ((c = getopt(argc, argv, "abf:o:")) != EOF) 
switch (c) { 
case ’a’: 

if (bflg) 

errflg++; 

else 

aflg++; 

break; 

case ’b’: 


if (aflg) 

errflg++; 

else 


bproc(); 

break; 
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case T: 

infile = optarg; 
break; 

case ’o’: 

ofile = optarg; 
bufsiza= 512; 
break; 

case ’?’: 

eirflg++; 

} 

if (errflg) { 

fprintf(stderr, "usage: . . . ’’); 
exit(2); 

} 

for (; optind < argc; optind++) { 

if (access(argv[optind], 4)) { 


} 
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NAME 

nice - set program priority 

SYNOPSIS 

nice(incr) 

DESCRIPTION 

The scheduling priority of the process is augmented by incr. Positive priorities get less service than nor- 
mal. Priority 10 is recommended to users who wish to execute long-running programs without flak from 
the administration. 

Negative increments are ignored except on behalf of the super-user. The priority is limited to the range 
-20 (most urgent) to 20 (least). 

The priority of a process is passed to a child process by fork( 2). For a privileged process to return to nor- 
mal priority from an unknown state, nice should be called successively with arguments —40 (goes to prior- 
ity —20 because of truncation), 20 (to get to 0), then 0 (to maintain compatibility with previous versions of 
this call). 

SEE ALSO 

nice(l), getpriority(2), setpriority(2), fork(2), renice(8) 
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NAME 

pause - stop until signal 

SYNOPSIS 

pause() 

DESCRIPTION 

Pause never returns normally. It is used to give up control while waiting for a signal from kill (2) or an 
interval timer, see setitimer(2). Upon termination of a signal handler started during a pause, the pause call 
will return. 

RETURN VALUE 

Always returns -1. 

ERRORS 

Pause always returns: 

[EINTR] The call was interrupted. 

SEE ALSO 

kill(2), select(2), sigpause(2) 
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NAME 

rand, srand - random number generator 

SYNOPSIS 

srand(seed) 
int seed; 

rand() 

DESCRIPTION 

Rand uses a multiplicative congruendal random number generator with period 2 32 to return successive 
pseudo-random numbers in the range from 0 to 2 31 -1. 

The generator is reinitialized by calling srand with 1 as argument It can be set to a random starting point 
by calling srand with whatever you like as argument. 

Random(i) is better; use it if compatibility is not a concern. 

SEE ALSO 

random(3) 

BUGS 

The low bits of the numbers generated are not very random; use the middle bits. In particular the lowest bit 
alternates between 0 and 1. 
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NAME 

stty, gtty - set and get terminal state 

SYNOPSIS 

#include <sgtty.h> 

stty(fd, buf) 
int fd; 

struct sgttyb *buf; 

gtty(fd, buf) 
int fd; 

struct sgttyb *buf; 

DESCRIPTION 

This interface is obsoleted by ioctI(2). 

Stty sets the state of the terminal associated with fd. Gtty retrieves the state of the terminal associated with 
fd. To set the state of a terminal the call must have write permission. 

The stty call is actually “ioctl(fd, TIOCSETP, buf)”, while the gtty call is “ioctl(fd, TIOCGETP, buf)”. 
See ioctl(2) and tty (4) for an explanation. 

DIAGNOSTICS 

If the call is successful 0 is returned, otherwise -1 is returned and the global variable errno contains the 
reason for the failure. 

SEE ALSO 

ioctl(2), tty(4) 
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NAME 

time, ftime - get date and time 

SYNOPSIS 

timeofday = time(O) 

timeofday = time(tloc) 
long *tloc; 

#include <sys/types.h> 

#include <sys/timeb.h> 

ftime(tp) 

struct timeb *tp; 

DESCRIPTION 

Time returns the time since 00:00:00 GMT, Jan. 1, 1970, measured in seconds. 

If tloc is nonnull, the return value is also stored in the place to which tloc points. 

Th q ftime entry fills in a structure pointed to by its argument, as defined by <sysltimeb.h>: 
struct timeb 
{ 

timet time; 
unsigned short millitm; 
short timezone; 
short dstflag; 

}; 

The structure contains the time since the epoch in seconds, up to 1000 milliseconds of more-precise inter- 
val, the local time zone (measured in minutes of time westward from Greenwich), and a flag that, if 
nonzero, indicates that Daylight Saving time applies locally during the appropriate part of the year. 

SEE ALSO 

date(l), gettimeofday(2), settimeofday(2), ctime(3) 
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TIMES ( 3C ) 


NAME 

times - get process times 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/times.h> 

times(buffer) 
struct tms *buffer; 

DESCRIPTION 

This interface is obsoleted by getrusage(2). 

Times returns time-accounting information for the current process and for the terminated child processes of 
the current process. All times are in 1/HZ seconds, where HZ is 60. 

This is the structure returned by times : 

struct tms { 


timet 

tmsutime; 

/* user time *1 

timet 

tmsstime; 

I* system time */ 

timet 

tmscutime; 

1* user time, children */ 

timet 

tmscstime; 

/* system time, children *1 


}; 

The children times are the sum of the children’s process times and their children’s times. 
SEE ALSO 

time(l), getrusage(2), wait3(2), time(3C) 
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TMPNAM ( 3C ) 


NAME 

tmpnam - create a name for a temporary file 
SYNOPSIS 

#include <stdio.h> 

char *tmpnam(s) 
char *s; 

DESCRIPTION 

This routine is included for System V compatibility. 

Tmpnam generates a file name that can safely be used for a temprary file. If (int)j is zero, tmpnam leaves 
its result in an internal static area and returns a pointer to that area. The next call to tmpnam will destroy 
the contents of the area. If (int)j is nonzero, s is assumed to be the address of an array of at least 
L_tmpnam bytes; tmpnam places its result in that array and returns s as its value. 

Tmpnam generates a different file name each time it is called. 

Files created using tmpnam and either fopen or creat are only temporary in the sense that they reside in a 
directory intended for temporary use, and their names are unique. It is the user’s responsibility to use 
unlink (2) to remove the file when its use is ended. 

SEE ALSO 

creat(2), unlink(2), mktemp(3), fopen(3S) 

BUGS 

If called more than 17,576 times in a single process, tmpnam will start recycling previously used names. 

Between the time a file name is created and the file is opened, it is possible for some other process to create 
a file with the same name. This can never happen if that other process is using tmpnam or mktemp, and the 
file names are chosen so as to render duplication by other means unlikely. 
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ULIMIT ( 3C ) 


NAME 

ulimit - get and set user limits 
SYNOPSIS 

long ulimit(cmd, newlimit) 
int cmd; 

DESCRIPTION 

This function is included for System V compatibility. 

This routine provides for control over process limits. The cmd values available are: 

1 Get the process’s file size limit The limit is in units of 512-byte blocks and is inherited by child 
processes. Files of any size can be read. 

2 Set the process’s file size limit to the value of newlimit. Any process may decrease this limit, but 
only a process with an effective user ID of super-user may increase the limit. Ulimit will fail and 
the limit will be unchanged if a process with an effective user ID other than the super-user 
attempts to increase its file size limit. 

3 Get the maximum possible break value. Seebrk(2). 

RETURN VALUE 

Upon successful completion, a non-negative value is returned. Otherwise a value of -1 is returned and 
errno is set to indicate the error. 

SEE ALSO 

brk(2), setrlimit(2), write(2) 
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UTIME(3C) 


NAME 

utime - set file times 
SYNOPSIS 

#include <sys/types.h> 

utime(file, timep) 
char *file; 
time_t timep[2]; 

DESCRIPTION 

The utime call uses the ‘accessed’ and ‘updated’ times in that order from the timep vector to set the 
corresponding recorded times for file. 

The caller must be the owner of the file or the super-user. The ‘inode-changed’ time of the file is set to the 
current time. 

SEE ALSO 

utimes(2), stat(2) 
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VLIMIT (3C) 


NAME 

vlimit - control maximum system resource consumption 
SYNOPSIS 

#include <sys/vlimit.h> 
v!imit(resource, value) 

DESCRIPTION 

This facility is superseded by getrlimit(2). 

Limits the consumption by the current process and each process it creates to not individually exceed value 
on the specified resource. If value is specified as -1, then the current limit is returned and the limit is 
unchanged. The resources which are currently controllable are: 

LIM_N OR AISE A pseudo-limit; if set non-zero then the limits may not be raised. Only the super-user 
may remove the noraise restriction. 

LIM_CPU the maximum number of cpu-seconds to be used by each process 
LIM_FSIZE the largest single file which can be created 

LIM_DATA the maximum growth of the data+stack region via sbrk(2) beyond the end of the pro- 
gram text 

LIM STACK the maximum size of the automatically-extended stack region 
LIM_CORE the size of the largest core dump that will be created. 

LIM_M[AXRSS a soft limit for the amount of physical memory (in bytes) to be given to the program. If 
memory is tight, the system will prefer to take memory from processes which are 
exceeding their declared LIM MAXRSS. 

Because this information is stored in the per-process information this system call must be executed directly 
by the shell if it is to affect all future processes created by the shell; limit is thus a built-in command to 
cj/i(1). 

The system refuses to extend the data or stack space when the limits would be exceeded in the normal way; 
a break call fails if the data space limit is reached, or the process is killed when the stack limit is reached 
(since the stack cannot be extended, there is no way to send a signal!). 

A file i/o operation which would create a file which is too large will cause a signal SIGXFSZ to be gen- 
erated, this normally terminates the process, but may be caught. When the cpu time limit is exceeded, a 
signal SIGXCPU is sent to the offending process; to allow it time to process the signal it is given 5 seconds 
grace by raising the cpu time limit. 

SEE ALSO 

csh(l) 

BUGS 

If LIM_NORAISE is set, then no grace should be given when the cpu time limit is exceeded. 

There should be limit and unlimit commands in sh(l) as well as in csh. 
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VTIMES (3C) 


NAME 

vtimes - get information about resource utilization 
SYNOPSIS 

vtimes(par_vm, chvm) 
struct vtimes *par_vm, *ch_vm; 

DESCRIPTION 

This facility is superseded by getrusage(2). 

Vtimes returns accounting information for the current process and for the terminated child processes of the 
current process. Either par_ym or ch_vm or both may be 0, in which case only the information for the 
pointers which are non-zero is returned. 

After the call, each buffer contains information as defined by the contents of the include file 
<sys/vtimes.h> : 

struct vtimes { 

int vmutime; /* user time (*HZ) */ 

int vm_stime; I* system time (*HZ) */ 

/* divide next two by utime+stime to get averages */ 


unsigned vm_idsrss; 

/* integral of d+s rss */ 

unsigned vm ixrss; 

/* integral of text rss */ 

int 

vmjnaxrss; 

/* maximum rss */ 

int 

vmjnajflt; 

/* major page faults */ 

int 

vmjninflt; 

/* minor page faults */ 

int 

vmnswap; 

/* number of swaps */ 

int 

vminblk; 

/* block reads */ 

int 

vmoublk; 

/* block writes */ 


}; 

The vm utime and vmjtime fields give the user and system time respectively in 60ths of a second (or 50ths 
if that is the frequency of wall current in your locality.) The vmidrss and vmixrss measure memory 
usage. They are computed by integrating the number of memory pages in use each over cpu time. They 
are reported as though computed discretely, adding the current memory usage (in 512 byte pages) each 
time the clock ticks. If a process used 5 core pages over 1 cpu-second for its data and stack, then vmjdsrss 
would have the value 5*60, where vm_utime+vm_stime would be the 60. Vmjdsrss integrates data and 
stack segment usage, while vmjxrss integrates text segment usage. Vmjnaxrss reports the maximum 
instantaneous sum of the text+data+stack core-resident page count. 

The vmjnajflt field gives the number of page faults which resulted in disk activity; the vmminflt field 
gives the number of page faults incurred in simulation of reference bits; vmnswap is the number of swaps 
which occurred. The number of file system input/output events are reported in vminblk and vm_oublk 
These numbers account only for real i/o; data supplied by the caching mechanism is charged only to the 
first process to read or write the data. 

SEE ALSO 

getrusage(2), wait3(2) 
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INTRO (3M) 


NAME 

intro - introduction to mathematical library functions 
DESCRIPTION 

These functions constitute the math library, libm. They are automatically loaded as needed by the Fortran 
compiler /77(1). The link editor searches this library under the “-lm” option. Declarations for these 
functions may be obtained from the include file <math.h>. 

LIST OF FUNCTIONS 


Name 

Appears on Page 

Description 

acos 

sin.3m 

trigonometric functions 

asin 

sin.3m 

trigonometric functions 

a tan 

sin.3m 

trigonometric functions 

atan2 

sin.3m 

trigonometric functions 

cabs 

hypot.3m 

Euclidean distance 

ceil 

floor.3m 

absolute value, floor, ceiling functions 

cos 

sin.3m 

trigonometric functions 

cosh 

sinh.3m 

hyperbolic functions 

exp 

exp. 3m 

exponential, logarithm, power, square root 

fabs 

floor.3m 

absolute value, floor, ceiling functions 

floor 

floor.3m 

absolute value, floor, ceiling functions 

gamma 

gamma.3m 

log gamma function 

hypot 

hypot.3m 

Euclidean distance 

jo 

j0.3m 

bessel functions 

jl 

j0.3m 

bessel functions 

jn 

j0.3m 

bessel functions 

log 

exp.3m 

exponential, logarithm, power, square root 

loglO 

exp.3m 

exponential, logarithm, power, square root 

pow 

exp.3m 

exponential, logarithm, power, square root 

sin 

sin.3m 

trigonometric functions 

sinh 

sinh.3m 

hyperbolic functions 

sqrt 

exp.3m 

exponential, logarithm, power, square root 

tan 

sin.3m 

trigonometric functions 

tanh 

sinh.3m 

hyperbolic functions 

yO 

j0.3m 

bessel functions 

yi 

j0.3m 

bessel functions 

yn 

j0.3m 

bessel functions 
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EXP(3M) 


NAME 

exp, log, log 10, pow, sqrt - exponential, logarithm, power, square root 

SYNOPSIS 

#include <math.h> 

double exp(x) 
double x; 

double log(x) 
double x; 

double logl0(x) 
double x; 

double pow(x, y) 
double x, y; 

double sqrt(x) 
double x; 

DESCRIPTION 

Exp returns the exponential function of x. 

Log returns the natural logarithm of x; loglO returns the base 10 logarithm. 

Pow returns x*. 

Sqrt returns the square root of x. 

SEE ALSO 

hypot(3M), sinh(3M), intro(2) 

DIAGNOSTICS 

These functions handle exceptional arguments in the spirit of IEEE standard P754 for binary floating point 
arithmetic, sqrt(x) for x < 0, log(x) for x < 0, loglO(x) for x < 0, pow(0.0,0.0), pow(inflnity,0.0), and 
pow(1.0,infinity) are invalid, as is pow(x,y) if x < 0 and y is not an integer value or infinite value; in all 
these cases NaN function values are returned and ermo is set to EDOM. 
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FLOOR (3M) 


NAME 

fabs, floor, ceil - absolute value, floor, ceiling functions 

SYNOPSIS 

#include <math.h> 

double floor(x) 
double x; 

double ceil(x) 
double x; 

double fabs(x) 
double x; 

DESCRIPTION 

Fabs returns the absolute value | jc |. 

Floor returns the value of the greatest integer less than or equal to x. 
Ceil returns the value of the least integer greater than or equal to x. 

SEE ALSO 

abs(3) 
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GAMMA ( 3M ) 


NAME 

gamma - log gamma function 

SYNOPSIS 

#include <math.h> 

double gamma(x) 
double x; 

DESCRIPTION 

Gamma returns In | T( | x | ) | . The sign of T( | x \ ) is returned in the external integer signgam. The follow- 
ing C program might be used to calculate T: 

y = gamma(x); 

#ifdef vax 

if (y > 88.0) 

#endif 
#ifdef sun 

if (y> 706.0) 

#endif 

error(); 
y = exp(y); 
iffsigngam) 

y = -y; 

DIAGNOSTICS 

A huge value is returned for negative integer arguments. 

BUGS 

There should be a positive indication of error. 
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HYPOT ( 3M ) 


NAME 

hypot, cabs - Euclidean distance 

SYNOPSIS 

#include <math.h> 

double hypot(x, y) 
double x, y; 

double cabs(z) 
struct { double x, y ;} z; 

DESCRIPTION 

Hypot and cabs return 

sqrt(x*x + y*y), 

taking precautions against unwarranted overflows. 

SEE ALSO 

exp(3M) for sqrt 
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JO ( 3M ) 


NAME 

jO, jl, jn, yO, yl, yn - bessel functions 
SYNOPSIS 

#include <math.h> 

double jO(x) 
double x; 

double jl(x) 
double x; 

double jn(n,x) 
double x; 

double yO(x) 
double x; 

double yl(x) 
double x; 

double yn(n, x) 
double x; 

DESCRIPTION 

These functions calculate Bessel functions of the first and second kinds for real arguments and integer ord- 
ers. 

DIAGNOSTICS 

Negative arguments cause yO, yl, andyn to return a huge negative value and set err no to EDOM. 
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SIN ( 3M ) 


NAME 

sin, cos, tan, asin, acos, atan, atan2 - trigonometric functions 

SYNOPSIS 

#include <math.h> 

double sin(x) 
double x; 

double cos(x) 
double x; 

double asin(x) 
double x; 

double acos(x) 
double x; 

double atan(x) 
double x; 

double atan2(y, x) 
double x, y; 

DESCRIPTION 

Sin, cos and tan return trigonometric functions of radian arguments. 

Asin returns the arc sin in the range -jc/ 2 to n/2. 

Acos returns the arc cosine in the range 0 to jt. 

Atan returns the arc tangent of x in the range -n/2 to n/2. 

Atan2 returns the arc tangent of y/x in the range -n to jt. 

DIAGNOSTICS 

These functions handle exceptional arguments in the spirit of IEEE standard P754 for binary floating point 
arithmetic. When x is infinity in sin(x), cos(x), or tan(x), or when |x| > 1 in asin(x) or acos(x), the functions 
return NaN values and ermo is set to EDOM. 
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SINH ( 3M ) 


NAME 

sinh, cosh, tanh - hyperbolic functions 

SYNOPSIS 

#include <math.h> 

double sinh(x) 
double x; 

double cosh(x) 
double x; 

double tanh(x) 
double x; 

DESCRIPTION 

These functions compute the designated hyperbolic functions for real arguments. 

DIAGNOSTICS 

These functions handle exceptional arguments in the spirit of IEEE standard P754 for binary floating point 
arithmetic. Thus sinh and cosh return infinity on overflow. 
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INTRO (3N) 


NAME 

intro - introduction to network library functions 
DESCRIPTION 

This section describes functions that are applicable to the DARPA Internet network, which are part of the 
standard C library. 

LIST OF FUNCTIONS 


Name 

Appears on Page 

Description 

endhostent 

gethostent.3n 

get network host entry 

endnetent 

getnetent.3n 

get network entry 

endprotoent 

getprotoent.3n 

get protocol entry 

endservent 

getservent.3n 

get service entry 

gethostbyaddr 

gethostent.3n 

get network host entry 

gethostbyname 

gethostent.3n 

get network host entry 

gethostent 

gethostent.3n 

get network host entry 

getnetbyaddr 

getnetent.3n 

get network entry 

getnetbyname 

getnetent.3n 

get network entry 

getnetent 

getnetent3n 

get network entry 

getprotobyname 

getprotoent.3n 

get protocol entry 

getprotobynumber 

getprotoent.3n 

get protocol entry 

getprotoent 

getprotoent.3n 

get protocol entry 

getrpcent 

getrpcent.3n 

get rpc entry 

getrpcbyname 

getrpcent.3n 

get rpc entry 

getrpcbynumber 

getrpcent.3n 

get rpc entry 

getservbyname 

getservent.3n 

get service entry 

getservbyport 

getservent.3n 

get service entry 

getservent 

getservent.3n 

get service entry 

htonl 

byteorder.3n 

convert values between host and network byte order 

htons 

byteorder.3n 

convert values between host and network byte order 

inet_addr 

ineL3n 

Internet address manipulation 

inetjnaof 

inet.3n 

Internet address manipulation 

inetmakeaddr 

inet.3n 

Internet address manipulation 

inet_netof 

inet.3n 

Internet address manipulation 

inet_network 

inet.3n 

Internet address manipulation 

inetntoa 

inet.3n 

Internet address manipulation 

ntohl 

byteorder.3n 

convert values between host and network byte order 

ntohs 

byteorder.3n 

convert values between host and network byte order 

rcmd 

rcmd.3n 

routines for returning a stream to a remote command 

rexec 

rexec.3n 

return stream to a remote command 

rresvport 

rcmd.3n 

routines for returning a stream to a remote command 

ruserok 

rcmd.3n 

routines for returning a stream to a remote command 

sethostent 

gethostent.3n 

get network host entry 

setnetent 

getnetent. 3n 

get network entry 

setprotoent 

getprotoent.3n 

get protocol entry 

setservent 

getservent.3n 

get service entry 
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BYTEORDER (3N) 


NAME 

htonl, htons, ntohl, ntohs - convert values between host and network byte order 
SYNOPSIS 

#include <sys/types.h> 

#include <netinet/in.h> 

netlong = htonl(hostlong); 
ujong netlong, hostlong; 

netshort = htons(hostshort); 
u_short netshort, hostshort; 

hostlong = ntohl(netlong); 
u_long hostlong, netlong; 

hostshort = ntohs(netshort); 
u_short hostshort, netshort; 

DESCRIPTION 

These routines convert 16 and 32 bit quantities between network byte order and host byte order. On 
machines such as the Sun these routines are defined as null macros in the include file <netinetlin.h>. 

These routines are most often used in conjunction with Internet addresses and ports as returned by 
gethostentQN) and getservent( 3N). 

SEE ALSO 

gethostent(3N), getservent(3N) 

BUGS 

The VAX handles bytes backwards from most everyone else in the world. This is not expected to be fixed 
in the near future. 
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NAME 

etherntoa, ether_aton, etherntohost, ether_hostton, ether line - ethemet address mapping operations 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

#include <net/if.h> 

#include <netinet/in.h> 

#include <netinet/if_ether.h> 

char * 

etherntoa(e) 

struct ether_addr *e; 

struct ether_addr * 
ether_aton(s) 

char *s; 

ether_ntohost(hostname, e) 
char *hostname; 
struct ether addr *e; 

ether_hostton(hostname, e) 
char * hostname; 
struct ether_addr *e; 

ether_line(l, e, hostname) 
char *1; 

struct ether_addr *e; 
char * hostname; 

DESCRIPTION 

These routines are useful for mapping 48 bit ethemet numbers to their ASCII representations or their 
corresponding host names, and vice versa. 

The function ether ntoa converts a 48 bit ethemet number pointed to by e to its standard ACSII representa- 
tion; it returns a pointer to the ASCII string. The representation is of the form: “x:x:x:x:x:x” where x is a 
hexadecimal number between 0 and ff. The function ether aton converts an ASCII string in the standard 
representation back to a 48 bit ethemet number; the function returns NULL if the string cannot be scanned 
successfully. 

The function ether ntohost maps an ethemet number (pointed to by e) to its associated hostname. The 
string pointed to by hostname must be long enough to hold the hostname and a null character. The function 
returns zero upon success and non-zero upon failure. Inversely, the function ether hostton maps a host- 
name string to its corresponding ethemet number; the function modifies the ethemet number pointed to by 
e. The function also returns zero upon success and non-zero upon failure. 

The function ether Jine scans a line (pointed to by l) and sets the hostname and the ethemet number 
(pointed to by e). The string pointed to by hostname must be long enough to hold the hostname and a null 
character. The function returns zero upon success and non-zero upon failure. The format of the scanned 
line is described by ethers(5). 

FILES 

/etc/ethers (or the yellowpages’ maps ethers.byaddr and ethers.byname) 

SEE ALSO 

ethers(5) 
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GETHOSTENT (3N) 


NAME 

gethostent, gethostbyaddr, gethostbyname, sethostent, endhostent - get network host entry 

SYNOPSIS 

#include <netdb.h> 


struct hostent *gethostent() 

struct hostent *gethostbyname(name) 
char *name; 

struct hostent * gethostbyadd r (addr , Ien, type) 
char *addr; int len, type; 

sethostent(stayopen) 
int stayopen 

endhostentQ 


DESCRIPTION 

Gethostent, gethostbyname, and gethostbyaddr each return a pointer to an object with the following struc- 
ture containing the broken-out fields of a line in the network host data base, I etc/ hosts. 


struct 


}; 


hostent { 


char 

*h_name; 

1* official name of host */ 

char 

**h_aliases; 

/* alias list *1 

int 

haddrtype; 

1* address type */ 

int 

hlength; 

/* length of address */ 

char 

*h_addr;/* address */ 


The members of this structure are: 


hname 
haliases 
haddrtype 
hlength 
h addr 


Official name of the host. 

A zero terminated array of alternate names for the host. 

The type of address being returned; currently always AF INET. 

The length, in bytes, of the address. 

A pointer to the network address for the host. Host addresses are returned in network byte 
order. 


Gethostent reads the next line of the file, opening the file if necessary. 

Sethostent opens and rewinds the file. If the stayopen flag is non-zero, the host data base will not be closed 
after each call to gethostent (either directly, or indirectly through one of the other “gethost” calls). 

Endhostent closes the file. 


Gethostbyname and gethostbyaddr sequentially search from the beginning of the file until a matching host 
name or host address is found, or until EOF is encountered. Host addresses are supplied in network order. 

FILES 

/etc/hosts 

/etc/yp/domm'nname/hosts .byname 
/ etc/ yp/domainname /hosts. by addr 

SEE ALSO 

hosts(5), ypserv(8) 

DIAGNOSTICS 

Null pointer (0) returned on EOF or error. 
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BUGS 

All information is contained in a static area so it must be copied if it is to be saved. Only the Internet 
address format is currently understood. 
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GETNETENT (3N) 


NAME 

getnetent, getnetbyaddr, getnetbyname, setnetent, endnetent - get network entry 

SYNOPSIS 

#include <netdb.h> 

struct netent *getnetent() 

struct netent *getnetbyname(name) 
char *name; 

struct netent *getnetbyaddr(net, type) 
long net; 

setnetent(stayopen) 
int stayopen 

endnetentO 

DESCRIPTION 

Getnetent, getnetbyname, and getnetbyaddr each return a pointer to an object with the following structure 
containing the broken-out fields of a line in the network data base, letclnetworks. 

struct netent { 

char *n_name; /* official name of net */ 

char **n_aliases; /* alias list */ 

int naddrtype; /* net number type */ 

long nnet; /* net number */ 

}; 

The members of this structure are: 

n name The official name of the network. 

n_aliases A zero terminated list of alternate names for the network. 

n addrtype The type of the network number returned; currently only AF_INET. 

n_net The network number. Network numbers are returned in machine byte order. 

Getnetent reads the next line of the file, opening the file if necessary. 

Setnetent opens and rewinds the file. If the stayopen flag is non-zero, the net data base will not be closed 
after each call to getnetent (either directly, or indirectly through one of the other “getnet” calls). 

Endnetent closes the file. 

Getnetbyname and getnetbyaddr sequentially search from the beginning of the file until a matching net 
name or net address is found, or until EOF is encountered. Network numbers are supplied in host order. 

FILES 

/etc/networks 

/etc/yp/doffwmname/networks.byname 
iQlc/yp/domainname /networks .by addr 

SEE ALSO 

networks(5), ypserv(8) 

DIAGNOSTICS 

Null pointer (0) returned on EOF or error. 

BUGS 

All information is contained in a static area so it must be copied if it is to be saved. 

Only Internet network numbers are currently understood. 
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NAME 

getnetgrent, setnetgrent, endnetgrent, innetgr - get network group entry 
SYNOPSIS 

innetgr(netgroup, machine, user, domain) 
char *netgroup, ^machine, *user, ^domain; 

setnetgrent(netgroup) 
char *netgroup 

endnetgrentO 

getnetgrent(machinep, userp, domainp) 
char **machinep, **userp, **domainp; 

DESCRIPTION 

Inngetgr returns 1 or 0, depending on whether netgroup contains the machine, user, domain triple as a 
member. Any of the three strings machine, user, or domain can be NULL, in which case it signifies a wild 
card. 

Getnetgrent returns the next member of a network group. After the call, machinep will contain a pointer to 
a string containing the name of the machine part of the network group member, and similarly for userp and 
domainp. If any of machinep, userp or domainp is returned as a NULL pointer, it signifies a wild card. 
Getnetgrent will malloc space for the name. This space is released when a endnetgrent call is made. Get- 
netgrent returns 1 if it succeeding in obtaining another member of the network group, 0 if it has reached the 
end of the group. 

Setnetgrent establishes the network group from which getnetgrent will obtain members, and also restarts 
calls to getnetgrent from the beginning of the list. If the previous setnetgrent call was to a different net- 
work group, a endnetgrent call is implied. Endnetgrent frees the space allocated during the getnetgrent 
calls. 

FILES 

/etc/netgroup 

/etc/yp/domain/netgroup 

/etc/yp/domam/netgroup.byuser 

/etc/yp/doffwm/netgroup.byhost 
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NAME 

getprotoent, getprotobynumber, getprotobyname, setprotoent, endprotoent - get protocol entry 

SYNOPSIS 

#include <netdb.h> 

struct protoent *getprotoentO 

struct protoent *getprotobyname(name) 
char *name; 

struct protoent *getprotobynumber(proto) 
int proto; 

setprotoent(stayopen) 
int stayopen 

endprotoentO 

DESCRIPTION 

Getprotoent, getprotobyname, and getprotobynumber each return a pointer to an object with the following 
structure containing the broken-out fields of a line in the network protocol data base, I etc! protocols. 

struct protoent { 

char *p_name; I* official name of protocol */ 

char **p_aliases; /* alias list */ 

long pjproto; I* protocol number */ 

}; 

The members of this structure are: 
p name The official name of the protocol, 
p aliases A zero terminated list of alternate names for the protocol. 
p_proto The protocol number. 

Getprotoent reads the next line of the file, opening the file if necessary. 

Setprotoent opens and rewinds the file. If the stayopen flag is non-zero, the net data base will not be closed 
after each call to getprotoent (either directly, or indirectly through one of the other “getproto” calls). 

Endprotoent closes the file. 

Getprotobyname and getprotobynumber sequentially search from the beginning of the file until a matching 
protocol name or protocol number is found, or until EOF is encountered. 

FILES 

/etc/protocols 

/etc/yp/domaz'nnawK/protocols.byname 

/etc/yp/domamnawe/protocols.bynumber 

SEE ALSO 

protocols(5), ypserv(8) 

DIAGNOSTICS 

Null pointer (0) returned on EOF or error. 

BUGS 

All information is contained in a static area so it must be copied if it is to be saved. Only the Internet pro- 
tocols are currently understood. 
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NAME 

getrpcent, getrpcbyname, getrpcbynumber - get rpc entry 

SYNOPSIS 

#include <netdb.h> 

struct rpcent *getrpcent(3 

struct rpcent * getrpcbyname(name) 
char *name; 

struct rpcent *getrpcbynumber(number) 
int number; 

setrpcent(stayopen) 
int stayopen 

endrpcentO 

DESCRIPTION 

Getrpcent, getrpcbyname, and getrpcbynumber each return a pointer to an object with the following struc- 
ture containing the broken-out fields of a line in the rpc program number data base, letclrpc. 

struct rpcent { 

char *r_name; I* name of server for this rpc program *1 

char **r_aliases; /* alias list */ 

long r_number; I* rpc program number */ 

}; 

The members of this structure are: 
r name The name of the server for this rpc program, 
r aliases A zero terminated list of alternate names for the rpc program, 
r number The rpc program number for this service. 

Getrpcent reads the next line of the file, opening the file if necessary. 

Setrpcent opens and rewinds the file. If the stayopen flag is non-zero, the net data base will not be closed 
after each call to getrpcent (either direcdy, or indirectly through one of the other “getrpc” calls). 

Endrpcent closes the file. 

Getrpcbyname and getrpcbynumber sequentially search from the beginning of the file until a matching rpc 
program name or program number is found, or until EOF is encountered. 

FILES 

/etc/rpc 

Ictdypldomainname /rpc. bynumber 
SEE ALSO 

rpc(5), rpcinfo(8), ypservices(8) 

DIAGNOSTICS 

Null pointer (0) returned on EOF or error. 

BUGS 

All information is contained in a static area so it must be copied if it is to be saved. 
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NAME 

getservent, getservbyport, getservbyname, setservent, endservent - get service entry 
SYNOPSIS 

#include <netdb.h> 


struct servent *getservent() 

struct servent *getservbyname(name, proto) 
char *name, * proto; 

struct servent *getservbyport(port, proto) 
int port; char *proto; 

setservent(stayopen) 
int stayopen 

endserventO 


DESCRIPTION 

Getservent, getservbyname, and getservbyport each return a pointer to an object with the following struc- 
ture containing the broken-out fields of a line in the network services data base, /etc/services. 


struct 


}; 


servent { 


char 

*s_name; 

/* official name of service */ 

char 

**s_aliases; 

/* alias list */ 

long 

s_port; 

/* port service resides at */ 

char 

*s_proto; 

/* protocol to use */ 


The members of this structure are: 


s name The official name of the service. 

s_aliases A zero terminated list of alternate names for the service. 

s_port The port number at which the service resides. Port numbers are returned in network byte order. 
s_proto The name of the protocol to use when contacting the service. 

Getservent reads the next line of the file, opening the file if necessary. 

Setservent opens and rewinds the file. If the stayopen flag is non-zero, the net data base will not be closed 
after each call to getservent (either directly, or indirectly through one of the other “getserv” calls). 

Endservent closes the file. 


Getservbyname and getservbyport sequentially search from the beginning of the file until a matching proto- 
col name or port number is found, or until EOF is encountered. If a protocol name is also supplied (non- 
NULL), searches must also match the protocol. 

FILES 

/etc/services 

/etc/yp/cfomam/iamg/services.byname 
SEE ALSO 

getprotoent(3N), services(5), ypserv(8) 

DIAGNOSTICS 

Null pointer (0) returned on EOF or error. 

BUGS 

All information is contained in a static area so it must be copied if it is to be saved. Expecting port 
numbers to fit in a 32 bit quantity is probably naive. 


220 


Last change: 28 February 1985 


Sun Release 3.0 



INET ( 3N ) 


NETWORK FUNCTIONS 


INET ( 3N ) 


NAME 

inet inet_addr, inetjietwork, inet_makeaddr, inet_lnaof, inetnetof, inet_ntoa - Internet address manipula- 
tion 

SYNOPSIS 

#include <sys/types.h> 

#include <sys/socket.h> 

#include <netinet/in.h> 

#include <arpa/inet.h> 

unsigned long 
inet_addr(cp) 
char *cp; 

inet_network(cp) 
char *cp; 

struct in_addr 
inet_makeaddr(net, Ina) 
int net, Ina; 

inet_lnaof(in) 
struct in_addr in; 

inet_netof(in) 
struct in_addr in; 

char * 

inetntoa(in) 
struct in_addr in; 

DESCRIPTION 

The routines inetaddr and inetjietwork each interpret character strings representing numbers expressed in 
the Internet standard notation, returning numbers suitable for use as Internet addresses and Internet 
network numbers, respectively. The routine inetjnakeaddr takes an Internet network number and a local 
network address and constructs an Internet address from it. The routines inetjietof and inetjnaof break 
apart Internet host addresses, returning the network number and local network address part, respectively. 

The routine inetjitoa returns a pointer to a string in the base 256 notation “d.d.d.d” described below. 

All Internet address are returned in network order (bytes ordered from left to right). All network numbers 
and local address parts are returned as machine format integer values. 

INTERNET ADDRESSES 

Values specified using the notation take one of the following forms: 

a.b.c.d 

a.b.c 

a.b 

a 

When four parts are specified, each is interpreted as a byte of data and assigned, from left to right, to the 
four bytes of an Internet address. Note that when an Internet address is viewed as a 32-bit integer quantity 
on the VAX the bytes referred to above appear as “d.c.b.a”. That is, VAX bytes are ordered from right to 
left. 

When a three part address is specified, the last part is interpreted as a 16-bit quantity and placed in the right 
most two bytes of the network address. This makes the three part address format convenient for specifying 
Class B network addresses as “128.net.host”. 
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When a two part address is supplied, the last part is interpreted as a 24-bit quantity and placed in the right 
most three bytes of the network address. This makes the two part address format convenient for specifying 
Class A network addresses as ‘ ‘net.host’ ’ . 

When only one part is given, the value is stored directly in the network address without any byte rearrange- 
ment. 

All numbers supplied as “parts” in a notation may be decimal, octal, or hexadecimal, as specified in 
the C language (that is, a leading Ox or OX implies hexadecimal; otherwise, a leading 0 implies octal; other- 
wise, the number is interpreted as decimal). 

SEE ALSO 

gethostent(3N), getnetent(3N), hosts(5), networks(5), 

DIAGNOSTICS 

The value -1 is returned by inet addr and inetjietwork for malformed requests. 

BUGS 

The problem of host byte ordering versus network byte ordering is confusing. A simple way to specify 
Class C network addresses in a manner similar to that for Class B and Class A is needed. 

The return value from inetjitoa points to static information which is overwritten in each call. 
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NAME 

rcmd, rresvport, ruserok - routines for returning a stream to a remote command 
SYNOPSIS 

rem = rcmd(ahost, inport, locuser, remuser, cmd, fd2p); 
char **ahost; 
u_short inport; 

char *locuser, *remuser, *cmd; 
int *fd2p; 

s = rresvport(port); 
int *port; 

ruserok(rhost, superuser, ruser, luser); 
char *rhost; 
int superuser; 
char *ruser, * luser; 

DESCRIPTION 

Rcmd is a routine used by the super-user to execute a command on a remote machine using an authentica- 
tion scheme based on reserved port numbers. Rresvport is a routine which returns a descriptor to a socket 
with an address in the privileged port space. Ruserok is a routine used by servers to authenticate clients 
requesting service with rcmd. All three functions are present in the same file and are used by the rshd( 8C) 
server (among others). 

Rcmd looks up the host *ahost using gethostbyname (3N), returning -1 if the host does not exist. Other- 
wise *ahost is set to the standard name of the host and a connection is established to a server residing at the 
well-known Internet port inport. 

If the call succeeds, a socket of type SOCK_STREAM is returned to the caller, and given to the remote 
command as stdin and stdout. If fd2p is non-zero, then an auxiliary channel to a control process will be 
set up, and a descriptor for it will be placed in *fd2p. The control process will return diagnostic output 
from the command (unit 2) on this channel, and will also accept bytes on this channel as being UNIX sig- 
nal numbers, to be forwarded to the process group of the command. If fd2p is 0, then the stderr (unit 2 of 
the remote command) will be made the same as the stdout and no provision is made for sending arbitrary 
signals to the remote process, although you may be able to get its attention by using out-of-band data. 

The protocol is described in detail in rshd($C). 

The rresvport routine is used to obtain a socket with a privileged address bound to it This socket is suit- 
able for use by rcmd and several other routines. Privileged addresses consist of a port in the range 0 to 
1023. Only the super-user is allowed to bind an address of this sort to a socket 

Ruserok takes a remote host’s name, as returned by a gethostent(3N) routine, two user names and a flag 
indicating if the local user’s name is the super-user. It then checks the files / etc! hosts. equiv and, possibly, 
.r hosts in the current working directory (normally the local user’s home directory) to see if the request for 
service is allowed. A 1 is returned if the machine name is listed in the “hosts.equiv” file, or the host and 
remote user name are found in the “.rhosts” file; otherwise ruserok returns 0. If the superuser flag is 1, 
the checking of the “hostiequiv” file is bypassed. 

SEE ALSO 

rlogin(lC), rsh(lC), rexec(3N), rexecd(8C), rlogind(8C), rshd(8C) 

BUGS 

There is no way to specify options to the socket call which rcmd makes. 
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NAME 

rexec - return stream to a remote command 
SYNOPSIS 

rem = rexec(ahost, inport, user, passwd, and, fd2p); 

char **ahost; 

u_short inport; 

char *user, -passwd, *cmd; 

int *fd2p; 

DESCRIPTION 

Rexec looks up the host *ahost using gethostbyname( 3N), returning -1 if the host does not exist Other- 
wise *ahost is set to the standard name of the host If a username and password are both specified, then 
these are used to authenticate to the foreign host; otherwise the environment and then the user’s .netrc file 
in his home directory are searched for appropriate information. If all this fails, the user is prompted for the 
information. 

The port inport specifies which well-known DARPA Internet port to use for the connection; it will nor- 
mally be the value returned from the call “getservbyname(”exec", "tcp”)” (see getservent(M)). The pro- 
tocol for connection is described in detail in rexecd( 8C). 

If the call succeeds, a socket of type SOCK_STREAM is returned to the caller, and given to the remote 
command as stdin and stdout. If fdlp is non-zero, then a auxiliary channel to a control process will be 
setup, and a descriptor for it will be placed in *fd2p. The control process will return diagnostic output 
from the command (unit 2) on this channel, and will also accept bytes on this channel as being UNIX sig- 
nal numbers, to be forwarded to the process group of the command. If fd2p is 0, then the stderr (unit 2 of 
the remote command) will be made the same as the stdout and no provision is made for sending arbitrary 
signals to the remote process, although you may be able to get its attention by using out-of-band data. 

SEE ALSO 

rcmd(3N), rexecd(8C) 

BUGS 

There is no way to specify options to the socket call which rexec makes. 
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NAME 

rpc - library routines for remote procedure calls 
DESCRIPTION 

These routines allow C programs to make procedure calls on other machines across the network. First, the 
client calls a procedure to send a data packet to the server. Upon receipt of the packet, the server calls a 
dispatch routine to perform the requested service, and then sends back a reply. Finally, the procedure call 
returns to the client. 


FUNCTIONS 

auth_destroy() 

authnone_create() 

authunix_create() 

authunix_create_default() 

callrpc() 

clnt_broadcast() 

clnt_call() 

clnt_destroy() 

clnt_freeres() 

clnt_geterr() 

clnt_pcreateerror() 

clnt_permo() 

clnt_perror() 

clntraw_create() 

clnttcp_create() 

clntudp_create() 

get_myaddress() 

pmapj>etmaps() 

pmap_getport() 

pmap_rmtcall() 

pmap_set() 

pmap_unset() 

registerrpc() 

rpc_createerr 

svc_destroy() 

svc_fds 

svc_freeargs() 

svc_getargs() 

svc_getcaller() 

svcj>etreq() 

svc_register() 

svc_run() 

svc_sendreply() 

svc_unregister() 

svcerr_auth() 

svcerr_decode() 

svcerr_noproc() 

svcerr_noprog() 

svcerr_progvers() 

svcerr_systemerr() 

svcerr_weakauth() 

svcraw_create() 

svctcp_create() 

svcudp_create() 

xdr_accepted_reply() 


destroy authentication information handle 

return RPC authentication handle with no checking 

return RPC authentication handle with UNIX permissions 

return default UNIX authentication handle 

call remote procedure, given [prognum, versnum,procnum] 

broadcast remote procedure call everywhere 

call remote procedure associated with client handle 

destroy client’s RPC handle 

free data allocated by RPC/XDR system when decoding results 

copy error information from client handle to error structure 

print message to stderr about why client handle creation failed 

print message to stderr corresponing to condition given 

print message to stderr about why RPC call failed 

create toy RPC client for simulation 

create RPC client using TCP transport 

create RPC client using UDP transport 

get the machine’s IP address 

return list of RPC program-to-port mappings 

return port number on which waits supporting service 

instructs portmapper to make an RPC call 

establish mapping between [prognum,versnum,procnum] and port 

destroy mapping between [prognum,versnum,procnum] and port 

register procedure with RPC service package 

global variable indicating reason why client creation failed 

destroy RPC service transport handle 

global variable with RPC service file descriptor mask 

free data allocated by RPC/XDR system when decoding arguments 

decodes the arguments of an RPC request 

get the network address of the caller of a procedure 

returns when all associated sockets have been serviced 

associates prognum and versnum with service dispatch procedure 

wait for RPC requests to arrive and call appropriate service 

send back results of a remote procedure call 

remove mapping of [prognum, versnum] to dispatch routines 

called when refusing service because of authentication error 

called when service cannot decode its parameters 

called when service hasn’t implemented the desired procedure 

called when program is not registered with RPC package 

called when version is not registered with RPC package 

called when service detects system error 

called when refusing service because of insufficient authentication 

creates a toy RPC service transport for testing 

creates an RPC service based on TCP transport 

creates an RPC service based on UDP transport 

generates RPC-style replies without using RPC package 
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xdr_authunix_parms() generates UNIX credentials without using RPC package 
xdr_callhdr() generates RPC-style headers without using RPC package 

xdr_callmsg() generates RPC-style messages without using RPC package 

xdr_opaque_auth() describes RPC messages, externally 

xdrjpmapO describes parameters for portmap procedures, externally 

xdr_pmaplist() describes a list of port mappings, externally 

xdr_rejected_reply() generates RPC-style rejections without using RPC package 
xdr_replymsg() generates RPC-style replies without using RPC package 

xprt_register() registers RPC service transport with RPC package 

xprt_unregister() unregisters RPC service transport from RPC package 

SEE ALSO 

Remote Procedure Call Programming Guide , in Networking on the Sun Workstation . 


226 


Last change: 22 July 1985 


Sun Release 3.0 



XDR ( 3N ) 


NETWORK FUNCTIONS 


XDR ( 3N ) 


NAME 

xdr - library routines for external data representation 
DESCRIPTION 

These routines allow C programmers to describe arbitrary data structures in a machine-independent 
fashion. Data for remote procedure calls are transmitted using these routines. 


FUNCTIONS 

xdr_array() 

xdr_bool() 

xdr_bytes() 

xdr_destroy() 

xdr_double() 

xdr_enum() 

xdr_float() 

xdr_getpos() 

xdr_inline() 

xdr_int() 

xdr_long() 

xdr_opaque() 

xdr_reference() 

xdr_setpos() 

xdr_short() 

xdr_string() 

xdr_u_int() 

xdr_u_long() 

xdr_u_short() 

xdr_union() 

xdr_void() 

xdr_wrapstring() 

xdrmem_create() 

xdrrec_create() 

xdrrec_endofrecord() 

xdrrec_eof() 

xdrrec_skiprecord() 

xdrstdiocreateQ 


translate arrays to/from external representation 
translate Booleans to/from external representation 
translate counted byte strings to/from external representation 
destroy XDR stream and free associated memory 
translate double precision to/from external representation 
translate enumerations to/from external representation 
translate floating point to/from external representation 
return current position in XDR stream 
invoke the in-line routines associated with XDR stream 
translate integers to/from external representation 
translate long integers to/from external representation 
translate fixed-size opaque data to/from external representation 
chase pointers within structures 
change current position in XDR stream 
translate short integers to/from external representation 
translate null-terminated strings to/from external representation 
translate unsigned integers to/from external representation 
translate unsigned long integers to/from external representation 
translate unsigned short integers to/from external representation 
translate discriminated unions to/from external representation 
always return one (1) 

package RPC routine for XDR routine, or vice-versa 

initialize an XDR stream 

initialize an XDR stream with record boundaries 

mark XDR record stream with an end-of-record 

mark XDR record stream with an end-of-file 

skip remaining record in XDR record stream 

initialize an XDR stream as standard I/O FILE stream 


SEE ALSO 

External Data Representation Protocol Specification, in Networking on the Sun Workstation. 
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NAME 

ypclnt yp_get_default_domain yp bind ypunbind yp match yp first yp_next yp all yp order ypmaster 
yperr_string ypproterr - yellow pages client interface 

SYNOPSIS 

#include <rpcsvc/ypclnt.h> 

yp_bind(indomain) ; 
char *indomain; 

void yp_unbind(indomain) 
char *indomain; 

yp_get_defauIt_domain(outdomain); 
char **outdomain; 

yp_match(indomain, inmap, inkey, inkeylen, outval, outvalien) 

char * indomain; 

char * inmap; 

char *inkey; 

int inkeylen; 

char **outvaI; 

int *outvallen; 

yp_first(indomain, inmap, outkey, outkeylen, outval, outvalien) 

char *indomain; 

char * inmap; 

char **outkey; 

int *outkeylen; 

char **outvaI; 

int *outval!en; 

yp_next(indomain, inmap, inkey, inkeylen, outkey, outkeylen, outval, outvalien); 

char * indomain; 

char * inmap; 

char *inkey; 

int inkeylen; 

char **outkey; 

int *outkeylen; 

char **outval; 

int *outva!len; 

yp_all(indomain, inmap, incallback); 
char * indomain; 
char * inmap; 

struct ypallcallback incallback; 

yp_order(indomain, inmap, outorder); 
char *indomain; 
char * inmap; 
int *outorder; 

yp_master(indomain, inmap, outname); 
char *indomain; 
char * inmap; 
char **outname; 

char *yperr_string(incode) 
int incode; 
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ypprot_err(incode) 
unsigned int incode; 

DESCRIPTION 

This package of functions provides an interface to the yellow pages (YP) network lookup service. The 
package can be loaded from the standard library, llib/libc.a. Refer to ypfiles(5) and ypserv(8) for an over- 
view of the yellow pages, including the definitions of map and domain , and a description of the various 
servers, databases, and commands that comprise the YP. 

All input parameters names begin with in. Output parameters begin with out. Output parameters of type 
char ** should be addresses of uninitialized character pointers. Memory is allocated by the YP client 
package using malloc{ 3), and may be freed if the user code has no continuing need for it. For each outkey 
and outval, two extra bytes of memory are allocated at the end that contain NEWLINE and NU LL, respec- 
tively, but these two bytes are not reflected in outkeylen or outvallen . indomain and inmap strings must be 
non-null and null-terminated. String parameters which are accompanied by a count parameter may not be 
null, but may point to null strings, with the count parameter indicating this. Counted strings need not be 
null-terminated. 

All functions in this package of type int return 0 if they succeed, and a failure code (YPERR jccoc) other- 
wise. Failure codes are described under DIAGNOSTICS below. 

The YP lookup calls require a map name and a domain name, at minimum. It is assumed that the client pro- 
cess knows the name of the map of interest Client processes should fetch the node’s default domain by 
calling yp_get_defauIt_domain() , and use the returned outdomain as the indomain parameter to succes- 
sive YP calls. 

To use the YP services, the client process must be “bound” to a YP server that serves the appropriate 
domain using ypbind. Binding need not be done explicitly by user code; this is done automatically when- 
ever a YP lookup function is called, yp bind can be called directly for processes that make use of a backup 
strategy (e.g., a local file) in cases when YP services are not available. 

Each binding allocates (uses up) one client process socket descriptor; each bound domain costs one socket 
descriptor. However, multiple requests to the same domain use that same descriptor. yp_unbind() is avail- 
able at the client interface for processes that explicitly manage their socket descriptors while accessing 
multiple domains. The call to ypunbindQ make the domain unbound, and free all per-process and per- 
node resources used to bind it. 

If an RPC failure results upon use of a binding, that domain will be unbound automatically. At that point, 
the ypclnt layer will retry forever or until the operation succeeds, provided that ypbind is running, and 
either 

a) the client process can’t bind a server for the proper domain, or 

b) RPC requests to the server fail. 

If an error is not RPC-related, or if ypbind is not running, or if a bound ypserv process returns any answer 
(success or failure), the ypclnt layer will return control to the user code, either with an error code, or a suc- 
cess code and any results. 

ypjnatch returns the value associated with a passed key. This key must be exact; no pattern matching is 
available. 

yp Jurst returns the first key-value pair from the named map in the named domain. 

yp_next() returns the next key- value pair in a named map. The inkey parameter should be the outkey 
returned from an initial call to yp Jirst() (to get the second key-value pair) or the one returned from the nth 
call to yp_next() (to get the nth + second key- value pair). 

The concept of first (and, for that matter, of next) is particular to the structure of the YP map being process- 
ing; there is no relation in retrieval order to either the lexical order within any original (non-YP) data base, 
or to any obvious numerical sorting order on the keys, values, or key-value pairs. The only ordering 
guarantee made is that if the yp _first( ) function is called on a particular map, and then the yp_next() 
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function is repeatedly called on the same map at the same server until the call fails with a reason of 
YPERRNOMORE, every entry in the data base will be seen exactly once. Further, if the same sequence 
of operations is performed on the same map at the same server, the entries will be seen in the same order. 

Under conditions of heavy server load or server failure, it is possible for the domain to become unbound, 
then bound once again (perhaps to a different server) while a client is running. This can cause a break in 
one of the enumeration rules; specific entries may be seen twice by the client, or not at all. This approach 
protects the client from error messages that would otherwise be returned in the midst of the enumeration. 
The next paragraph describes a better solution to enumerating all entries in a map. 

yp all provides a way to transfer an entire map from server to client in a single request using TCP (rather 
than UDP as with other functions in this package). The entire transaction take place as a single RPC 
request and response. You can use yp_all just like any other YP procedure, identify the map in the normal 
manner, and supply the name of a function which will be called to process each key-value pair within the 
map. You return from the call to yp_a.ll only when the transaction is completed (successfully or unsuccess- 
fully), or your “foreach” function decides that it doesn’t want to see any more key-value pairs. 

The third parameter to yp_a.ll is 

struct ypallcallback *incallback { 
int (*foreach)(); 
char *data; 

}; 

The function foreach is called 

foreach(instatus, inkey, inkeylen, inval, invallen, indata); 

int instatus; 

char * inkey; 

int inkeylen; 

char * inval; 

int invalllen; 

char * indata; 

The instatus parameter will hold one of the return status values defined in <rpcsvc/yp_prot .h> — 
either YP_TRUE or an error code. (See ypprot err , below, for a function which converts a YP protocol 
error code to a ypclnt layer error code.) 

The key and value parameters are somewhat different than defined in the synopsis section above. First, the 
memory pointed to by the inkey and inval parameters is private to the yp_all function, and is overwritten 
with the arrival of each new key-value pair. It is the responsibility of the foreach function to do something 
useful with the contents of that memory, but it does not own the memory itself. Key and value objects 
presented to the foreach function look exactly as they do in the server’s map — if they were not newline- 
terminated or null-terminated in the map, they won’t be here either. 

The indata parameter is the contents of the incallback->data element passed to yp_all . The data element 
of the callback structure may be used to share state information between the foreach function and the main- 
line code. Its use is optional, and no part of the YP client package inspects its contents — cast it to some- 
thing useful, or ignore it as you see fit. 

The foreach function is a Boolean. It should return zero to indicate that it wants to be called again for 
further received key-value pairs, or non-zero to stop the flow of key-value pairs. If foreach returns a non- 
zero value, it is not called again; the functional value of yp_all is then 0. 

yp_order returns the order number for a map. 

ypjnaster returns the machine name of the master YP server for a map. 

yperr string returns a pointer to an error message string that is null-terminated but contains no period or 
newline. 
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ypprot_err takes a YP protocol error code as input, and returns a ypclnt layer error code, which may be 
used in turn as an input to yperr string . 

FILES 

/usr/include/rpcsvc/ypclnt.h 

/usr/include/rpcsvc/yp_prot.h 

SEE ALSO 

ypfiles(5), ypserv(8), 

DIAGNOSTICS 

All integer functions return 0 if the requested operation is successful, or one of the following errors if the 
operation fails. 


#define YPERRBADARGS 
#define YPERRRPC 
#define YPERRDOMAIN 
#define YPERR MAP 


#define YPERRKEY 
#define YPERRYPERR 
#define YPERRRESRC 
#define YPERRNOMORE 
#define YPERRPMAP 
#define YPERR_YPBIND 
#define YPERRYPSERV 
#define YPERR NODOM 


1 /* args to function are bad */ 

2 /* RPC failure - domain has been unbound */ 

3 /* can’t bind to server on this domain */ 

4 /* no such map in server’s domain */ 

5 /* no such key in map */ 

6 I* internal yp server or client error */ 

7 I* resource allocation failure */ 

8 I* no more records in map database */ 

9 I* can’t communicate with portmapper */ 

10 /* can’t communicate with ypbind */ 

11/* can’t communicate with ypserv */ 

12 /* local domain name not set */ 
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NAME 

intro - introduction to RPC service library functions 
DESCRIPTION 

These functions constitute the RPC service library, librpcsvc. In order to get the link editor to load this 
library, use the -lrpcsvc option of cc. Declarations for these functions may be obtained from various 
include files <rpcsvc/*.h>. 


LIST OF FUNCTIONS 

routine on page 

description 

ether 

ether(3R) 

monitor traffic on the Ethernet 

getrpcport 

getrpcport(3R) get RPC port number 

havedisk 

rstat(3R) 

determine if remote machine has disk 

mount 

mount(3R) 

keep track of remotely mounted filesystems 

musers 

musers(3R) 

return number of users on remote machine 

rquota 

rquota(3R) 

implement quotas on remote machines 

rstat 

rstat(3R) 

get performance data from remote kernel 

rusers 

musers(3R) 

return information about users on remote machine 

rwall 

rwall(3R) 

write to specified remote machines 

spray 

spray(3R) 

scatter data in order to check the network 

yppasswd 

yppasswd(3R) 

update user password in yellow pages 
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NAME 

ether - monitor traffic on the Ethernet 
SYNPOSIS 

#include <rpcsvc/ether.h> 

RPC INFO 

program number 

ETHERPROG 

xdr routines: 

xdr_etherstat(xdrs, es) 

XDR *xdrs; 
struct etherstat *es; 
xdr_etheraddrs(xdrs, ea) 

XDR *xdrs; 
struct etheraddrs *ea; 
xdr_etherhtable(xdrs, hm) 

XDR *xdrs; 

struct etherhmem **hm; 
xdr_etherhmem(xdrs, hm) 

XDR *xdrs; 

struct ethedimem **hm; 
xdr_etherhbody(xdrs, hm) 

XDR *xdrs; 
struct etherhmem *hm; 
xdr_addrmask(xdrs, am) 

XDR *xdrs; 
struct addrmask *am; 

Xdr etherhmem processes a single etherhmem structure. Xdr_etherhtable processes an array of 
HASHSIZE *struct etherhmems. The ** etherhmem field of etheraddrs is actually a hashtable, 
that is, it is a pointer to an array of HASHSIZE hmem pointers. 

procs: 

ETHERPROC_GETDATA 

no args, returns struct etherstat 
ETHERPROCON 

no args or results, puts server in promiscuous mode 
ETHERPROCOFF 

no args or results, puts server in promiscuous mode 
ETHERPROC_GETSRCDATA 

no args, returns struct etheraddrs with information 
about source of packets 
ETHERPROCGETDSTDATA 

no args, returns struct etheraddrs with information 
about destination of packets 
ETHERPROC_SELECTSRC 

takes struct mask as argument, no results 
sets a mask for source 
ETHERPROCJSELECTDST 

takes struct mask as argument, no results 
sets a mask for dst 
ETHERPROC_SELECTPROTO 

takes struct mask as argument, no results 
sets a mask for proto 
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ETHERPROC_SELECTLNTH 

takes struct mask as argument, no results 
sets a mask for Inth 

versions: 

ETHERVERSORIG 

structures: 

/* 

* all ether stat’s except sue, dst addresses 
*/ 

struct etherstat { 

struct timeval e_time; 

unsigned long ebytes; 

unsigned long e_packets; 

unsigned long ebcast; 

unsigned long e_size[NBUCKETS]; 

unsigned long e_proto[NPROTOS] ; 

}; 

I* 

* member of address hash table 
*/ 

struct etherhmem { 
int haddr; 
unsigned hcnt; 
struct etherhmem *h_nxt; 

}; 

/* 

* sre, dst address info 
*/ 

struct etheraddrs { 

struct timeval e_time; 

unsigned long e_bytes; 

unsigned long e_packets; 

unsigned long e bcast; 

struct etherhmem **e_addrs; 

}; 

I* 

* for size, a_addr is lowvalue, a_mask is high value 
*/ 

struct addrmask { 
int a_addr; 

int a_mask; /* 0 means wild card *1 

}; 

SEE ALSO 

traffic(?), etherfind(?), etherd(?) 
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NAME 

getrpcport - get RPC port number 
SYNOPSIS 

int getrpcport(host, prognum, versnum, proto) 
char *host; 

int prognum, versnum, proto; 

DESCRIPTION 

Getrpcport returns the port number for version versnum of the RPC program prognum running on host and 
using protocol proto. It returns 0 if it cannot contact the portmapper, or if prognum is not registered. If 
prognum is registered but not with version versnum, it will return that port number. 
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NAME 

mount - keep track of remotely mounted filesystems 
SYNOPSIS 

#include <rpcsvc/mount.h> 

RPC INFO 

program number 

MOUNTPROG 

xdr routines: 

xdr_exportbody(xdrs, ex) 

XDR *xdrs; 
struct exports *ex; 
xdr_exports(xdrs, ex); 

XDR *xdrs; 
struct exports **ex; 
xdr_fhandle(xdrs, fh); 

XDR *xdrs; 
fhandlet *fp; 
xdr_fhstatus(xdis, fhs); 

XDR *xdrs; 
struct fhstatus *fhs; 
xdr_groups(xdrs, gr); 

XDR *xdrs; 
struct groups *gr; 
xdr_mountbody(xdrs, ml) 

XDR *xdrs; 
struct mountlist *ml; 
xdr_mountlist(xdrs, ml); 

XDR *xdrs; 
struct mountlist **ml; 
xdr_path(xdrs, path); 

XDR *xdrs; 
char **path; 

procs: 

MOUNTPROC_MNT 

argument of xdr_path, returns fhstatus. 
Requires unix authentication. 
MOUNTPROCDUMP 

no args, returns struct mountlist 
MOUNTPROCJJMNT 

argument of xdr_path, no results, 
requires unix authentication. 
MOUNTPROCJJMNT ALL 

no arguments, no results, 
requires unix authentication, 
umounts all remote mounts of sender. 
MOUNTPROCEXPORT 
MOUNTPROC_EXPORTALL 

no args, returns struct exports 

versions: 

MOUNT VERS_ORIG 
structures: 
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struct mountlist { /* what is mounted */ 

char *ml_name; 
char *ml_path; 
struct mountlist *ml_nxt; 

}; 

struct fhstatus { 

int fhsstatus; 
fhandle_t fhsfh; 

}; 

/* 

* List of exported directories 

* An export entry with ex groups 

* NULL indicates an entry which is exported to the world. 

*/ 


struct exports { 

dev_t 

exdev; 

/* dev of directory */ 

char 

*ex_name; 

I* name of directory */ 

struct groups 

*ex_groups; 

/* groups allowed to mount this entry */ 

struct exports 

*ex_next; 


J > 

struct groups { 

char 

*g_name; 


struct groups 

*g_next; 



}; 


SEE ALSO 

mount(8), showmount(8), mountd(8C), NFS Protocol Spec, section 3. 
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NAME 

musers, rusers - return information about users on remote machines 
SYNOPSIS 

#include <rpcsvc/rusers.h> 

rnusers(host) 

char *host 

rusers(host, up) 

char *host 

struct utmpidlearr *up; 

DESCRIPTION 

Rnusers returns the number of users logged on to host (-1 if it cannot determine that number). Rusers fills 
the utmpidlearr structure with data about host, and returns 0 if successful. The relevant structures are: 

struct utmparr { /* RUSERSVERS_ORIG */ 

struct utmp **uta_arr; 
int utacnt 

}; 

struct utmpidle { 

struct utmp uiutmp; 
unsigned uiidle; 

}; 

struct utmpidlearr { /* RUSERS VERSIDLE */ 

struct utmpidle **uia_arr; 
int uiacnt 

}; 

RPC INFO 

program number 

RUSERSPROG 

xdr routines: 

int xdr_utmp(xdrs, up) 

XDR *xdrs; 
struct utmp *up; 
int xdr_utmpidle(xdrs, ui); 

XDR *xdrs; 
struct utmpidle *ui; 
int xdr_utmpptr(xdrs, up); 

XDR *xdrs; 
struct utmp **up; 
int xdr_utmpidleptr(xdrs, up); 

XDR *xdrs; 
struct utmpidle **up; 
int xdr_utmparr(xdrs, up); 

XDR *xdrs; 
struct utmparr *up; 
int xdr_utmpidlearr(xdrs, up); 

XDR *xdrs; 

struct utmpidlearr *up; 

procs: 

RU SERSPROCNUM 

No arguments, returns number of users as an unsigned long. 


238 


Last change: 10 August 1985 


Sun Release 3.0 



RNUSERS(3R) 


RPC SERVICES 


RNUSERS ( 3R ) 


RUSERSPROCNAMES 

No arguments, returns utmparr or utmpidlearr, depending on version number. 
RUSERSPROCALLNAMES 

No arguments, returns utmparr or utmpidlearr, depending on version number. 
Returns listing even for utmp entries satisfying nonuser() in utmp.h. 

versions: 

RUSERSVERSORIG 

RUSERSVERSJDLE 

structures: 

SEE ALSO 

rusers(l), rusersd(8c) 
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NAME 

rquota - implement quotas on remote machines 
SYNPOSIS 

#include <rpcsvc/rquota.h> 

RPC INFO 

program number: 

RQUOTAPROG 

xdr routines: 

xdr_getquota_args(xdrs, gqa); 

XDR *xdrs; 

struct getquotaargs *gqa; 
xdr j>etquota_rslt(xdrs, gqr); 

XDR *xdrs; 

struct getquotarslt *gqr; 
xdr_rquota(xdrs, rq); 

XDR *xdrs; 
struct rquota *rq; 

procs: 

RQUOTAPROCGETQUOTA 

RQUOTAPROCGETACTIVEQUOTA 

Arguments of struct getquota args. 

Returns struct getquota rslt. 

Uses UNIX authentication. 

Returns quota only on filesystems with quota active. 

versions: 

RQUOTAVERSORIG 
structures: 

struct getquota_args { 

char *gqa_pathp; 
int gqauid; 

}; 

I* 

* remote quota structure 
*1 

struct rquota { 

int rq_bsize; 
boolt rq_active; 
ulong rq_bhardlimit; 
ulong rq_bsoftlimit; 
u_long rq_curblocks; 
ulong rq_fhardlimit; 
ulong rq_fsoftlimit; 
ulong rq_curfiles; 
u_long rq_btimeleft; 
ulong rq_ftimeleft; 

}; 

enum gqr status { 

Q_OK = 1, 

QNOQUOTA = 2, 

QEPERM = 3 

}; 


/* path to filesystem of interest */ 
/* inquire about quota for uid */ 


I* block size for block counts */ 

/* indicates whether quota is active */ 
/* absolute limit on disk blks alloc */ 
/* preferred limit on disk blks */ 

/* current block count */ 

/* absolute limit on allocated files */ 
/* preferred file limit */ 

/* current # allocated files *1 
/* time left for excessive disk use */ 

/* time left for excessive files */ 


/* quota returned */ 

/* noquota for uid */ 

/* no permission to access quota */ 
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struct getquota_rslt { 

enum gqrstatus gqr_status; /* discriminant */ 
struct rquota gqr rquota; /* valid if status == Q_OK */ 

}; 

SEE ALSO 

quota(l), quotactl(2) 
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NAME 

havedisk, rstat - get performance data from remote kernel 
SYNOPSIS 

#include <rpcsvc/rstat.h> 

havediskfhost) 

char *host; 

rstat(host, statp) 

char *host; 

struct statstime *statp; 

DESCRIPTION 

Havedisk returns 1 if host has a disk, 0 if it does not, and -1 if this cannot be determined. Rstat fills in the 

statstime structure for host, and returns 0 if it was successful. The relevant structures are: 

struct stats { /* RSTATVERS ORIG *1 

int cp_time[CPUSTATES]; 
int dk_xfer[DK_NDRIVE] ; 

unsigned v_pgpgin; /* these are cumulative sum */ 

unsigned v_pgpgout; 

unsigned v_pswpin; 

unsigned v_pswpout; 

unsigned vintr; 

int ifipackets; 

int ifierrors; 

int ifopackets; 

int ifoerrors; 

int ifcollisions; 

}; 

struct statsswtch { /* RSTATVERSSWTCH */ 

int cp_time[CPUSTATES]; 
int dk_xfer[DK_NDRIVE] ; 

unsigned vjpgpgin; /* these are cumulative sum */ 

unsigned v_pgpgout; 

unsigned vjpswpin; 

unsigned v_pswpout; 

unsigned v intr; 

int if ipackets; 

int if_ierrors; 

int if_opackets; 

int if oerrors; 

int if_collisions; 

unsigned v_swtch; 

long avenrun[3]; 

struct timeval boottime 

}; 

struct statstime { /* RSTATVERS_TIME */ 

int cp_time[CPUSTATES]; 
int dk_xfer[DK_NDRIVE] ; 

unsigned v_pgpgin; /* these are cumulative sum *1 

unsigned v_pgpgout; 

unsigned v_pswpin; 

unsigned v_pswpout; 

unsigned v intr; 
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int ifipackets; 
int ifierrors; 
int ifopackets; 
int if_oerrors; 
int ifcollisions; 
unsigned v_swtch; 
long avenrun[3]; 
struct timeval boottime; 
struct timeval curtime; 

}; 

RPC INFO 

program number: 

RSTATPROG 

xdr routines: 

int xdr_stats(xdrs, stat) 

XDR *xdrs; 
struct stats *stat; 
int xdr_statsswtch(xdrs, stat) 

XDR *xdrs; 
struct statsswtch *stat; 
int xdr_statstime(xdrs, stat) 

XDR *xdrs; 
struct statstime *stat; 
int xdr_timeval(xdrs, tv) 

XDR *xdrs; 
struct timeval *tv; 

procs: 

RSTATPROCHAVEDISK 

Takes no arguments, returns long which is true if remote host has a disk. 
RSTATPROCSTATS 

Takes no arguments, return struct statsxxx, depending on version. 

versions: 

RSTATVERSORIG 

RSTATVERSSWTCH 

RSTATVERSTIME 

SEE ALSO 

perfmeter(l), rup(l), rstatd(8c) 
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NAME 

rwall - write to specified remote machines 
SYNOPSIS 

#include <rpcsvc/rwall.h> 

rwall(host, msg); 

char *host, *msg; 

DESCRIPTION 

Rwcill causes host to print the string msg to all its users. It returns 0 if successful. 
RPC INFO 

program number: 

WALLPROG 

procs: 

WALLPROCWALL 

Takes string as argument (wrapstring), returns no arguments. 
Executes wall on remote host with string. 

versions: 

RSTATVERSORIG 

SEE ALSO 

rwall(l), shutdown(8), rwalld(8C) 
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NAME 

spray - scatter data in order to check the network 
SYNOPSIS 

tinclude <rpcsvc/spray.h> 

RPC INFO 

program number: 

SPRAYPROG 

xdr routines: 

xdr_sprayarr(xdrs, arr); 

XDR *xdrs; 
struct sprayarr *arr; 
xdr_spraycumul(xdrs, cumul); 

XDR *xdrs; 

sturct spraycumul *cumul; 

procs: 

SPRAYPROCSPRAY 

Takes no arguments, returns no value. 

Increments a counter in server daemon. 

The server does not return this call, so the caller should have a timeout of 0. 
SPRAYPROCGET 

Takes no arguments, returns struct spraycumul with value of counter and clock. 
SPRAYPROCCLEAR 

Takes no arguments and returns no value. 

Zeros out counter and clock. 

versions: 

SPRAYVERSORIG 

structures: 

struct spraycumul { 

unsigned counter; 
struct timeval clock; 

}; 

struct sprayarr { 
int *data, 
int lnth 

}; 

SEE ALSO 

spray(8), sprayd(8) 
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NAME 

yppasswd - update user password in yellow pages 
SYNPOSIS 

#include <rpcsvc/yppasswd.h> 

yppasswd(oldpass, newpw) 
char *oldpass 
struct passwd *newpw; 

DESCRIPTION 

If oldpass is indeed the old user password, this routine replaces the password entry with newpw. It returns 
0 if successful. 

RPC INFO 

program number 

YPPASSWDPROG 

xdr routines: 

xdr_ppasswd(xdrs, yp) 

XDR *xdrs; 
struct yppasswd *yp; 
xdr_yppasswd(xdrs, pw) 

XDR *xdrs; 
stmct passwd *pw; 

procs: 

YPPASSWDPROCUPDATE 

Takes struct yppasswd as argument, returns integer. 

Same behavior as yppasswd() wrapper. 

Uses UNIX authentication. 

versions: 

YPPASSWD VERSORIG 

structures: 

stmct yppasswd { 

char *oldpass; /* old (unencrypted) password */ 
stmct passwd newpw; /* new pw structure */ 

}; 

SEE ALSO 

yppasswd(l), yppasswdd(8C) 
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NAME 

stdio — standard buffered input/output package 

SYNOPSIS 

#include <stdio.h> 

FILE *stdin; 

FILE *stdout; 

FILE *stderr; 

DESCRIPTION 

The functions described in section 3S constitute a user-level buffering scheme. The in-line macros getc 
and putc (5S) handle characters quickly. The higher level routines gets, f gets, scanf, fscanf, fread, puts, 
fputs, printf ,fprintf ,fwrite all use getc and putc ; they can be freely intermixed. 

A file with associated buffering is called a stream, and is declared to be a pointer to a defined type FILE. A 
fopen{ 3S) creates certain descriptive data for a stream and returns a pointer to designate the stream in all 
further transactions. There are three normally open streams with constant pointers declared in the include 
file and associated with the standard open files: 

sfdin standard input file 

stdouf standard output file 

stderr standard error file 

A constant ‘pointer’ NULL (0) designates no stream at all. 

An integer constant EOF (-1) is returned upon end of file or error by integer functions that deal with 
streams. 

Any routine that uses the standard input/output package must include the header file <stdio.h> of pertinent 
macro definitions. The functions and constants mentioned in sections labeled 3S are declared in the 
include file and need no further declaration. The constants, and the following ‘functions’ are implemented 
as macros; redeclaration of these names is perilous: getc, get char, putc, put char, feof, f error, fileno, 
clrerr. 


SEE ALSO 

open(2), close(2), read(2), write(2), fread(3S), fseek(3S) 

DIAGNOSTICS 

The value EOF is returned uniformly to indicate that a FILE pointer has not been initialized with fopen, 
input (output) has been attempted on an output (input) stream, or a FILE pointer designates corrupt or oth- 
erwise unintelligible FILE data. 

For purposes of efficiency, this implementation of the standard library has been changed to line buffer out- 
put to a terminal by default and attempts to do this transparently by flushing the output whenever a read (2) 
from the standard input is necessary. This is almost always transparent, but may cause confusion or mal- 
functioning of programs which use standard i/o routines but use read (2) themselves to read from the stan- 
dard input. 

In cases where a large amount of computation is done after printing part of a line on an output terminal, it 
is necessary to fflush (see fclose( 3S)) the standard output before going off and computing so that the output 
will appear. 

BUGS 

The standard buffered functions do not interact well with certain other library and system functions, espe- 
cially vfork and abort. 


LIST OF FUNCTIONS 


Name 

Appears on Page Description 

clearerr 

ferror.3s 

stream status inquiries 

fclose 

fclose.3s 

close or flush a stream 

fdopen 

fopen.3s 

open a stream 
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feof 

ferror.3s 

stream status inquiries 

ferror 

ferror.3s 

stream status inquiries 

fflush 

fclose.3s 

close or flush a stream 

fgetc 

getc.3s 

get character or integer from stream 

fgets 

gets.3s 

get a string from a stream 

fileno 

ferror.3s 

stream status inquiries 

fopen 

fopen.3s 

open a stream 

fprintf 

printf.3s 

formatted output conversion 

fputc 

putc.3s 

put character or word on a stream 

fputs 

puts.3s 

put a string on a stream 

fread 

fread.3s 

buffered binary input/output 

freopen 

fopen.3s 

open a stream 

fscanf 

scanf.3s 

formatted input conversion 

fseek 

fseek.3s 

reposition a stream 

ftell 

fseek.3s 

reposition a stream 

fwrite 

fread.3s 

buffered binary input/output 

getc 

getc.3s 

get character or integer from stream 

getchar 

getc.3s 

get character or integer from stream 

gets 

gets.3s 

get a string from a stream 

getw 

getc.3s 

get character or integer from stream 

pclose 

popen.3s 

initiate I/O to/from a process 

popen 

popen.3s 

initiate I/O to/from a process 

printf 

printf.3s 

formatted output conversion 

putc 

putc.3s 

put character or word on a stream 

putchar 

putc.3s 

put character or word on a stream 

puts 

puts.3s 

put a string on a stream 

putw 

putc.3s 

put character or word on a stream 

rewind 

fseek.3s 

reposition a stream 

scanf 

scanf.3s 

formatted input conversion 

setbuf 

setbuf.3s 

assign buffering to a stream 

setbuffer 

setbuf.3s 

assign buffering to a stream 

setiinebuf 

setbuf.3s 

assign buffering to a stream 

sprintf 

printf.3s 

formatted output conversion 

sscanf 

scanf.3s 

formatted input conversion 

stdio 

intro.3s 

standard buffered input/output package 

ungetc 

ungetc.3s 

push character back into input stream 
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NAME 

fclose, fflush - close or flush a stream 

SYNOPSIS 

#include <stdio.h> 

fcIose(stream) 

FILE ^stream; 

fflush(stream) 

FILE *stream; 

DESCRIPTION 

Fclose causes any buffers for the named stream to be emptied, and the file to be closed. Buffers allocated 
by the standard input/output system are freed. 

Fclose is performed automatically upon calling exit(3). 

Fflush causes any buffered data for the named output stream to be written to that file. The stream remains 
open. 

SEE ALSO 

close(2), fopen(3S), setbuf(3S) 

DIAGNOSTICS 

These routines return EOF if stream is not associated with an output file, or if buffered data cannot be 
transferred to that file. 
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NAME 

ferror, feof, clearerr, fileno - stream status inquiries 

SYNOPSIS 

#include <stdio.h> 

feof(stream) 

FILE ^stream; 

ferror(stream) 

FILE ^stream 

clrerr(stream) 

FILE ^stream 

iileno(stream) 

FILE * stream; 

DESCRIPTION 

Feof returns non-zero when end of file is read on the named input stream, otherwise zero. 

Ferror returns non-zero when an error has occurred reading or writing the named stream, otherwise zero. 
Unless cleared by clearerr, the error indication lasts until the stream is closed. 

Clrerr resets the error indication on the named stream. 

Fileno returns the integer file descriptor associated with the stream, see open( 2). 

These functions are implemented as macros; they cannot be redeclared. 

SEE ALSO 

fopen(3S), open(2) 
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NAME 

fopen, freopen, fdopen - open a stream 

SYNOPSIS 

#include <stdio.h> 

FILE *fopen(filename, type) 
char * filename, *type; 

FILE *freopen(fi!ename, type, stream) 
char ^filename, *type; 

FILE *stream; 

FILE *fdopen(fildes, type) 
char *type; 

DESCRIPTION 

Fopen opens the file named by filename and associates a stream with it. Fopen returns a pointer to be used 
to identify the stream in subsequent operations. 

Type is a character string having one of the following values: 

"r" open for reading 

"w" create for writing 

"a" append: open for writing at end of file, or create for writing 

In addition, each type may be followed by a V to have the file opened for reading and writing. "r+" posi- 
tions the stream at the beginning of the file, ”w+" creates or truncates it, and "a+" positions it at the end. 
Both reads and writes may be used on read/write streams, with the limitation that an fseek, rewind, or read- 
ing an end-of-file must be used between a read and a write or vice-versa. 

Freopen substitutes the named file in place of the open stream. It returns the original value of stream. The 
original stream is closed. 

Freopen is typically used to attach the preopened constant names, stdin, stdout, stderr, to specified files. 

Fdopen associates a stream with a file descriptor obtained from open, dup, creat, or pipe (2). The type of 
the stream must agree with the mode of the open file. 

SEE ALSO 

open(2), fclose(3S) 

DIAGNOSTICS 

Fopen and freopen return the pointer NULL if filename cannot be accessed. 

BUGS 

Fdopen is not portable to systems other than UNIX. 

The read/write types do not exist on all systems. Those systems without read/write modes will probably 
treat the type as if the ’+’ was not present. These are unreliable in any event. 
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NAME 

fread, fwrite - buffered binary input/output 
SYNOPSIS 

#indude <stdio.h> 

fread(ptr, sizeof(*ptr), nitems, stream) 

FILE ^stream; 

fwrite(ptr, sizeof(*ptr), nitems, stream) 

FILE * stream; 

DESCRIPTION 

Fread reads, into a block beginning at ptr, nitems of data of the type of *ptr from the named input stream. 
It returns the number of items actually read. 

If stream is stdin and the standard output is line buffered, then any partial output line will be flushed before 
any call to read (2) to satisfy the fread. 

Fwrite appends at most nitems of data of the type of *ptr beginning at ptr to the named output stream. It 
returns the number of items actually written. 

SEE ALSO 

read(2), write(2), fopen(3S), getc(3S), putc(3S), gets(3S), puts(3S), printf(3S), scanf(3S) 

DIAGNOSTICS 

Fread and fwrite return 0 upon end of file or error. 
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NAME 

fseek, ftell, rewind - reposition a stream 

SYNOPSIS 

#include <stdio.h> 

fseek(stream, offset, ptrname) 

FILE * stream; 
long offset; 

long ftell(stream) 

FILE * stream; 

rewind(stream) 

DESCRIPTION 

Fseek sets the position of the next input or output operation on the stream. The new position is at the 
signed distance offset bytes from the beginning, the current position, or the end of the file, according as 
ptrname has the value 0, 1, or 2. 

Fseek undoes any effects of ungetc(3S). 

Ftell returns the current value of the offset relative to the beginning of the file associated with the named 
stream. It is measured in bytes on UNIX; on some other systems it is a magic cookie, and the only fool- 
proof way to obtain an offset for fseek. 

Rewind (stream) is equivalent to fseek(stream, 0L, 0). 

SEE ALSO 

lseek(2), fopen(3S) 

DIAGNOSTICS 

Fseek returns -1 for improper seeks. 
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NAME 

getc, getchar, fgetc, getw - get character or integer from stream 

SYNOPSIS 

#include <stdio.h> 

int getc(stream) 

FILE *stream; 

int getchar() 

int fgetc(stream) 

FILE *stream; 

int getw(stream) 

FILE ^stream; 

DESCRIPTION 

Getc returns the next character from the named input stream. 

Getchar () is identical to getc ( stdin ). 

Fgetc behaves like getc, but is a genuine function, not a macro; it may be used to save object text. 

Getw returns the next C int (word) from the named input stream. It returns the constant EOF upon end of 
file or error, but since that is a good integer value, feof and f error (3S) should be used to check the success 
of getw. Getw assumes no special alignment in the file. 

SEE ALSO 

fopen(3S), putc(3S), gets(3S), scanf(3S), fread(3S), ungetc(3S) 

DIAGNOSTICS 

These functions return the integer constant EOF at end of file or upon read error. 

A stop with message, ‘Reading bad file’, means an attempt has been made to read from a stream that has 
not been opened for reading by fopen. 

BUGS 

The end-of-file return from getchar is incompatible with that in UNIX editions 1-6. 

Because it is implemented as a macro, getc treats a stream argument with side effects incorrectly. In par- 
ticular, l getc(*f++);’ doesn’t work sensibly. 

Data files written and read with putw and getw are not portable; the size of an int and the order in which 
data bytes are stored within an int varies between machines. 
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NAME 

gets, fgets - get a string from a stream 

SYNOPSIS 

#indude <stdio.h> 

char *gets(s) 
char *s; 

char *fgets(s, n, stream) 
char *s; 

FILE *stream; 

DESCRIPTION 

Gets reads a string into s from the standard input stream stdin. The string is terminated by a newline char- 
acter, which is replaced in 5 by a null character. Gets returns its argument. 

Fgets reads n - 1 characters, or up to a newline character, whichever comes first, from the stream into the 
string s. The last character read into s is followed by a null character. Fgets returns its first argument. 

SEE ALSO 

puts(3S), getc(3S), scanf(3S), fread(3S), ferror(3S) 

DIAGNOSTICS 

Gets and fgets return the constant pointer NULL upon end of file or error. 

BUGS 

Gets deletes a newline, fgets keeps it, all in the name of backward compatibility. 
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NAME 

popen, pclose - initiate I/O to/from a process 
SYNOPSIS 

#include <stdio.h> 

FILE * popen (command, type) 
char ^command, *type; 

pclose(stream) 

FILE ^stream; 

DESCRIPTION 

The arguments to popen are pointers to null-terminated strings containing respectively a shell command 
line and an I/O mode, either "r" for reading or "w" for writing. It creates a pipe between the calling process 
and the command to be executed. The value returned is a stream pointer that can be used (as appropriate) 
to write to the standard input of the command or read from its standard output. 

A stream opened by popen should be closed by pclose, which waits for the associated process to terminate 
and returns the exit status of the command. 

Because open files are shared, a type "r” command may be used to filter stdin, and a type "w" to filter 
stdout. Popen always calls sh, never csh. 

SEE ALSO 

pipe(2), fopen(3S), fclose(3S), system(3), wait(2), sh(l) 

DIAGNOSTICS 

Popen returns a null pointer if files or processes cannot be created, or the shell cannot be accessed. 

Pclose returns -1 if stream is not associated with a ‘popened’ command. 

BUGS 

Buffered reading before opening an input filter may leave the standard input of that filter mispositioned. 
Similar problems with an output filter may be forestalled by careful buffer flushing, for instance, with 
/flush, see /close (3S). 
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NAME 

printf, fprintf, sprintf- formatted output conversion 

SYNOPSIS 

#include <stdio.h> 

int printf(format [, arg ] ... ) 
char *format; 

int fprintf(stream, format [, arg ] ... ) 

FILE ^stream; 
char ^format; 

char *sprintf(s, format [, arg ] ... ) 
char *s, format; 

#include <varargs.h> 
int _doprnt(format, args, stream) 
char ^format; 
va_list *args; 

FILE ^stream; 

DESCRIPTION 

Printf places output on the standard output stream stdout. Fprintf places output on the named output 
stream. Sprintf places ‘output’ in the string s, followed by the character ‘\0’. All of these routines work by 
calling the implementation-dependent routine doprnt, using the variable-length argument facilities of 
varargs( 3). Printf and fprintf return the number of characters transmitted, while sprintf returns a pointer to 
the string. Each returns an EOF if an output error was encountered. 

Each of these functions converts, formats, and prints its arguments after the first under control of the first 
argument. The first argument is a character string which contains two types of objects: plain characters, 
which are simply copied to the output stream, and conversion specifications, each of which causes conver- 
sion and printing of the next successive arg. 

Each conversion specification is introduced by the character %. Following the %, there may be 

• an optional minus sign which specifies left adjustment of the converted value in the indicated field; 

• an optional digit string specifying a field width ; if the converted value has fewer characters than the field 
width it is blank-padded on the left (or right, if the left-adjustment indicator has been given) to make up 
the field width; if the field width begins with a zero, zero-padding is done instead of blank-padding; 

• an optional period V which serves to separate the field width from the next digit string; 

• an optional digit string specifying a precision which specifies the number of digits to appear after the 
decimal point, for e- and f-conversion, or the maximum number of characters to be printed from a string; 

8 an optional *#’ character specifying that the value should be converted to an “alternate form”. For c, d, 
s, and u, conversions, this option has no effect For o conversions, the precision of the number is 
increased to force the first character of the output string to a zero. For x(X) conversion, a non-zero result 
has the string Ox(OX) prepended to it. For e, E, f, g, and G, conversions, the result always contains a 
decimal point even if no digits follow the point (normally, a decimal point only appears in the results of 
those conversions if a digit follows the decimal point). For g and G conversions, trailing zeros are not 
removed from the result as they would otherwise be. 

• the character 1 specifying that a following d, o, x, or u corresponds to a long integer arg. 

8 a character which indicates the type of conversion to be applied. 

A field width or precision may be instead of a digit string. In this case an integer arg supplies the field 
width or precision. 
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The conversion characters and their meanings are 

dox The integer arg is converted to decimal, octal, or hexadecimal notation respectively. 

f The float or double arg is converted to decimal notation in the style ‘[-]ddd.ddd’ where the 
number of d’s after the decimal point is equal to the precision specification for the argument. If 
the precision is missing, 6 digits are given; if the precision is explicitly 0, no digits and no decimal 
point are printed. 

e The float or double arg is converted in the style ‘[-]d.ddde±ddd’ where there is one digit before 
the decimal point and the number after is equal to the precision specification for the argument; 
when the precision is missing, 6 digits are produced. 

g The float or double arg is printed in style d, in style f, or in style e, whichever gives full precision 
in minimum space. 

The %e, %f, and %g formats print IEEE indeterminate values (infinity or not-a-number) as “Infinity” or 

“Nan” respectively. 

c The character arg is printed. 

s Arg is taken to be a string (character pointer) and characters from the string are printed until a null 
character or until the number of characters indicated by the precision specification is reached; 
however if the precision is 0 or missing all characters up to a null are printed. 

u The unsigned integer arg is converted to decimal and printed (the result is in the range 0 through 
MAXUINT, where MAXUINT equals 4294967295 on a Sun or on a VAX-11 and 65535 on a PDP- 
11 ). 

% Print a ‘ % ’ ; no argument is converted. 

In no case does a non-existent or small field width cause truncation of a field; padding takes place only if 

the specified field width exceeds the actual width. Characters generated by printfwte printed by putc{ 3S). 

Examples 

To print a date and time in the form ‘Sunday, July 3, 10:02’, where weekday and month are pointers to 

null-terminated strings: 

printf("%s, %s %d, %02d:%02d", weekday, month, day, hour, min); 

To print n to 5 decimals: 

printf("pi = %.5f, 4*atan(1.0)); 


SEE ALSO 

putc(3S), scanf(3S), ecvt(3) 

BUGS 

Very wide fields (>128 characters) fail. 

The values “Infinity” and “Nan” cannot be read by scanf{ 3S). 
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NAME 

putc, putchar, fputc, putw - put character or word on a stream 

SYNOPSIS 

#include <stdio.h> 

int putc(c, stream) 
char c; 

FILE *stream; 

putchar(c) 

fputc(c, stream) 

FILE ^stream; 

putw(w, stream) 

FILE *stream; 

DESCRIPTION 

Putc appends the character c to the named output stream. It returns the character written. 

Put charge) is defined as putc(c, stdout). 

Fputc behaves like putc, but is a genuine function rather than a macro. 

Putw appends C int (word) w to the output stream. It returns the integer written. Putw neither assumes nor 
causes special alignment in the file. 

SEE ALSO 

fopen(3S), fclose(3S), getc(3S), puts(3S), printf(3S), fread(3S) 

DIAGNOSTICS 

These functions return the constant EOF upon error. Since this is a good integer, ferror(3S) should be used 
to detect putw errors. 

BUGS 

Because it is implemented as a macro, putc treats a stream argument with side effects improperly. In par- 
ticular “putc(c, *f++)” doesn’t work sensibly. 

Errors can occur long after the call to putc. 

Data files written and read with putw and getw are not portable; the size of an int and the order in which 
data bytes are stored within an int varies between machines. 
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NAME 

puts, fputs - put a string on a stream 
SYNOPSIS 

#include <stdio.h> 

puts(s) 
char *s; 

fputs(s, stream) 
char *s; 

FILE *stream; 

DESCRIPTION 

Puts copies the null-terminated string 5 to the standard output stream stdout and appends a newline charac- 

Fputs copies the null-terminated string 5 to the named output stream. 

Neither routine copies the terminal null character. 

SEE ALSO 

fopen(3S), gets(3S), putc(3S), printf(3S), ferror(3S) 
fread(3S) for fwrite 

BUGS 

Puts appends a newline, fputs does not, all in the name of backward compatibility. 
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NAME 

scanf, fscanf, sscanf - formatted input conversion 

SYNOPSIS 

#include <stdio.h> 

scanf(format [ , pointer ] . . . ) 
char *format; 

fscanfrstream, format [ , pointer ] . . . ) 

FILE ^stream; 
char * format; 

sscanf(s, format [ , pointer ] . . . ) 
char *s, ^format; 

DESCRIPTION 

Scanf reads from the standard input stream stdin. Fscanf reads from the named input stream. Sscanf reads 
from the character string s. Each function reads characters, interprets them according to a format, and 
stores the results in its arguments. Each expects as arguments a control string format, described below, and 
a set of pointer arguments indicating where the converted input should be stored. 

The control string usually contains conversion specifications, which are used to direct interpretation of 
input sequences. The control string may contain: 

1. Blanks, tabs or newlines, which match optional white space in the input. 

2. An ordinary character (not %) which must match the next character of the input stream. 

3. Conversion specifications, consisting of the character %, an optional assignment suppressing charac- 
ter *, an optional numerical maximum field width, and a conversion character. 

A conversion specification directs the conversion of the next input field; the result is placed in the variable 
pointed to by the corresponding argument, unless assignment suppression was indicated by *. An input 
field is defined as a string of non-space characters; it extends to the next inappropriate character or until the 
field width, if specified, is exhausted. 

The conversion character indicates the interpretation of the input field; the corresponding pointer argument 
must usually be of a restricted type. The following conversion characters are legal: 

% a single is expected in the input at this point; no assignment is done. 

d a decimal integer is expected; the corresponding argument should be an integer pointer. 

o an octal integer is expected; the corresponding argument should be a integer pointer. 

x a hexadecimal integer is expected; the corresponding argument should be an integer pointer. 

s a character string is expected; the corresponding argument should be a character pointer pointing to an 
array of characters large enough to accept the string and a terminating ‘\0\ which will be added. The 
input field is terminated by a space character or a newline. 

c a character is expected; the corresponding argument should be a character pointer. The normal skip 
over space characters is suppressed in this case; to read the next non-space character, try ‘%ls’. If a 
field width is given, the corresponding argument should refer to a character array, and the indicated 
number of characters is read. 

e a floating point number is expected; the next field is converted accordingly and stored through the 
f corresponding argument, which should be a pointer to a float. The input format for floating point 
numbers is an optionally signed string of digits possibly containing a decimal point, followed by an 
optional exponent field consisting of an E or e followed by an optionally signed integer. 

[ indicates a string not to be delimited by space characters. The left bracket is followed by a set of char- 
acters and a right bracket; the characters between the brackets define a set of characters making up the 
string. If the first character is not circumflex (“), the input field is all characters until the first 
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character not in the set between the brackets; if the first character after the left bracket is \ the input 
field is all characters until the first character which is in the remaining set of characters between the 
brackets. The corresponding argument must point to a character array. 

The conversion characters d, o and x may be capitalized or preceded by I to indicate that a pointer to long 
rather than to int is in the argument list Similarly, the conversion characters e or f may be capitalized or 
preceded by 1 to indicate a pointer to double rather than to float. The conversion characters d, o and x may 
be preceded by h to indicate a pointer to short rather than to int. 

The scanf functions return the number of successfully matched and assigned input items. This can be used 
to decide how many input items were found. The constant EOF is returned upon end of input; note that this 
is different from 0, which means that no conversion was done; if conversion was intended, it was frustrated 
by an inappropriate character in the input. 

For example, the call 

int i; float x; char name[50]; 
scanf("%d%f%s", &i, &x, name); 

with the input line 

25 54.32E-1 thompson 

will assign to i the value 25, x the value 5.432, and name will contain ‘thompson\0 ’ . Or, 

int i; float x; char name[50]; 
scanf("%2d%f%*d%[1234567890]\ &i, &x, name); 

with input 

56789 0123 56a72 

will assign 56 to i, 789.0 to x, skip ‘0123’, and place the string ‘56\0’ in name. The next call to getchar 
will return ‘a’. 

SEE ALSO 

atof(3), getc(3S), printf(3S) 

DIAGNOSTICS 

The scanf functions return EOF on end of input, and a short count for missing or illegal data items. 

BUGS 

The success of literal matches and suppressed assignments is not directly determinable. 

Scanf cannot read the strings which printf{ 3S) generates for IEEE indeterminate floating point values. 

Scanf provides no way to convert a number in any arbitrary base (decimal, hex or octal) based on the tradi- 
tional C conventions (leading 0 or Ox). 
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NAME 

setbuf, setbuffer, setlinebuf - assign buffering to a stream 

SYNOPSIS 

#indude <stdio.h> 

setbuf(stream, huf) 

FILE ^stream; 
char *buf; 

setbuffer(stream, buf, size) 

FILE ^stream; 
char *bof; 
int size; 

setlinebuf(stream) 

FILE *stream; 

DESCRIPTION 

The three types of buffering available are unbuffered, block buffered, and line buffered. When an output 
stream is unbuffered, information appears on the destination file or terminal as soon as written; when it is 
block buffered many characters are saved up and written as a block; when it is line buffered characters are 
saved up until a newline is encountered or input is read from stdin. F flush (see fclose{ 3S)) may be used to 
force the block out early. Normally all files are block buffered. A buffer is obtained from malloc( 3) upon 
the first getc or putc(3S) on the file. If the standard stream stdout refers to a terminal it is line buffered. If 
the standard stream stderr refers to a terminal it is line buffered. 

Setbuf is used after a stream has been opened but before it is read or written. The character array buf is 
used instead of an automatically allocated buffer. If buf is the constant pointer NULL, input/output will be 
completely unbuffered. A manifest constant BUFSIZ tells how big an array is needed: 

char buf [BUFSIZ]; 

Setbuffer, an alternate form of setbuf, is used after a stream has been opened but before it is read or writ- 
ten. The character array buf whose size is determined by the size argument is used instead of an automati- 
cally allocated buffer. If buf is the constant pointer NULL, input/output will be completely unbuffered. 

Setlinebuf is used to change stdout or stderr (only) from block buffered or unbuffered to line buffered. 
Unlike setbuf and setbuffer it can be used at any time that the file descriptor is active. 

A file can be changed from unbuffered or line buffered to block buffered by using freopen (see f open 1 3S)). 
A file can be changed from block buffered or line buffered to unbuffered by using freopen followed by set- 
buf v/ith a buffer argument of NULL. 

SEE ALSO 

fopen(3S), getc(3S), putc(3S), malloc(3), fclose(3S), puts(3S), printf(3S), ffead(3S) 
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NAME 

ungetc - push character back into input stream 

SYNOPSIS 

#inc!ude <stdio.h> 

ungetc(c, stream) 

FILE ^stream; 

DESCRIPTION 

Ungetc pushes the character c back on an input stream. That character will be returned by the next getc 
call on that stream. Ungetc returns c . 

One character of pushback is guaranteed provided something has been read from the stream and the stream 
is actually buffered. Attempts to push EOF are rejected. 

An/jeek(3S) erases all memory of pushed back characters. 

SEE ALSO 

getc(3S), setbuf(3S), fseek(3S) 

DIAGNOSTICS 

Ungetc returns EOF if it can’t push a character back. 
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NAME 

intro - introduction to other libraries 
DESCRIPTION 

This section contains manual pages describing other libraries, which are available only from C. The list 
below includes libraries which provide device independent plotting functions, terminal independent screen 
management routines for two dimensional non-bitmap display terminals, and functions for managing data 
bases with inverted indexes. All functions are located in separate libraries indicated in each manual entry. 

FILES 

/usr/lib/libcurses.a screen management routines (see curses( 3x)) 

/usr/lib/libdbm.a data base management routines (see dbm( 3x)) 

/usr/lib/libmp.a multiple precision math library (see mp (3x)) 

/usr/lib/libplot.a plot routines (see plot(3x)) 

/usr/lib/lib300.a " 

/usr/lib/lib300s.a 

/usr/lib/lib450.a " 

/usr/lib/lib4014.a " 

/usr/lib/libtermcap.a terminal handling routines (see termcap( 3x)) 

/usr/lib/libtermcap_p.a 

/usr/lib/libtermlib.a 

/usr/lib/libtermlib_p.a 
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NAME 

curses - screen functions with “optimal” cursor motion 
SYNOPSIS 

cc [ flags ] files -lcurses -ltermcap [ libraries ] 

DESCRIPTION 

These routines give the user a method of updating screens with reasonable optimization. They keep an 
image of the current screen, and the user sets up an image of a new one. Then the refresh() tells the rou- 
tines to make the current screen look like the new one. In order to initialize the routines, the routine 
initscr() must be called before any of the other routines that deal with windows and screens are used. The 
routine endwin() should be called before exiting. 

SEE ALSO 

ioctl(2), getenv(3), tty(4), termcap(5) 

FUNCTIONS 


addch(ch) 

add a character to stdscr 

addstr(str) 

add a string to stdscr 

box(win,vert,hor) 

draw a box around a window 

crmode() 

set cbreak mode 

clear() 

clear stdscr 

clearok(scr,boolf) 

set clear flag for scr 

clrtobot() 

clear to bottom on stdscr 

clrtoeol() 

clear to end of line on stdscr 

delch() 

delete a character 

deleteln() 

delete a line 

delwin(win) 

delete win 

echo() 

set echo mode 

endwin() 

end window modes 

erase() 

erase stdscr 

getch() 

get a char through stdscr 

getcap(name) 

get terminal capability name 

getstr(str) 

get a string through stdscr 

gettmode() 

get tty modes 

getyx(win,y,x) 

get (y,x) co-ordinates 

inch() 

get char at current (y,x) co-ordinates 

initscr() 

initialize screens 

insch(c) 

insert a char 

insertln() 

insert a line 

leaveok(win,boolf) 

set leave flag for win 

longname(termbuf,name) 

get long name from termbuf 

move(y,x) 

move to (y,x) on stdscr 

mvcur(lasty,lastx,newy,newx) 

actually move cursor 

newwin(lines,cols,begin y, begin x) 

create a new window 

nl() 

set newline mapping 

nocrmode() 

unset cbreak mode 

noecho() 

unset echo mode 

nonl() 

unset newline mapping 

noraw() 

unset raw mode 

overlay(win 1 , win2) 

overlay winl on win2 

overwrite(win 1 ,win2) 

overwrite winl on top of win2 

printw(fmt,argl,arg2,...) 

printf on stdscr 

raw() 

set raw mode 

refresh() 

make current screen look like stdscr 

resetty() 

reset tty flags to stored value 
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savettyO 

scanw(fmt,argl,arg2,...) 

scroll(win) 

scrollok(win,boolf) 

setterm(name) 

standend() 

standout!) 

subwin(win, lines, cols, begin_y,begin_x) 

touchwin(win) 

unctrl(ch) 

waddch(win.ch) 

waddstr(win,str) 

wclear(win) 

wclrtobot(win) 

wclrtoeol(win) 

wdelch(win,c) 

wdeleteln(win) 

werase(win) 

wgetch(win) 

wgetstr(win,str) 

winch(win) 

winsch(win,c) 

winsertln(win) 

wmove(win,y,x) 

wprintw(win,fmt,argl,arg2,...) 

wrefresh(win) 

wscanw(win,fmt,argl,arg2,...) 

wstandend(win) 

wstandout(win) 


stored current tty flags 
scanf through stdscr 
scroll win one line 
set scroll flag 

set term variables for name 
end standout mode 
start standout mode 
create a subwindow 
“change” all of win 
printable version of ch 
add char to win 
add string to win 
clear win 

clear to bottom of win 
clear to end of line on win 
delete char from win 
delete line from win 
erase win 

get a char through win 

get a string through win 

get char at current (y,x) in win 

insert character into win 

insert line into win 

set current (y,x) co-ordinates on win 

printf on win 

make screen look like win 
scanf through win 
end standout mode on win 
start standout mode on win 
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NAME 

dbminit, fetch, store, delete, firstkey, nextkey — data base subroutines 
SYNOPSIS 

typedef struct { 

char *dptr; 
int dsize; 

} datum; 

dbminit(file) 
char *file; 

datum fetch(key) 
datum key; 

store(key, content) 
datum key, content; 

delete(key) 
datum Bcey; 

datum firstkeyO 

datum nextkey(key) 
datum key; 

dbmcloseO 

DESCRIPTION 

These functions maintain key/content pairs in a data base. The functions will handle very large (a billion 
blocks) databases and will access a keyed item in one or two file system accesses. The functions are 
obtained with the loader option -Idbm. 

Keys and contents are described by the datum typedef. A datum specifies a string of dsize bytes pointed to 
by dptr. Arbitrary binary data, as well as normal ASCII strings, are allowed. The data base is stored in two 
files. One file is a directory containing a bit map and has ‘.dir’ as its suffix. The second file contains all 
data and has ‘.pag’ as its suffix. 

Before a database can be accessed, it must be opened by dbminit. At the time of this call, the files file .dir 
andyi/e.pag must exist. (An empty database is created by creating zero-length ‘.dir’ and ‘.pag’ files.) 

Once open, the data stored under a key is accessed by fetch and data is placed under a key by store. A key 
(and its associated contents) is deleted by delete. A linear pass through all keys in a database may be 
made, in an (apparently) random order, by use of firstkey and nextkey. Firstkey will return the first key in 
the database. With any key nextkey will return the next key in the database. This code will traverse the 
data base: 

for (key = firstkeyO; key .dptr != NULL; key = nextkey(key)) 

A database may be closed by calling dbmclose. You must close a database before opening a new one. 
DIAGNOSTICS 

All functions that return an int indicate errors with negative values. A zero return indicates ok. Routines 
that return a datum indicate errors with a null (0) dptr. 

BUGS 

The ‘.pag’ file will contain holes so that its apparent size is about four times its actual content. Older 
UNIX systems may create real file blocks for these holes when touched. These files cannot be copied by 
normal means (cp, cat, tp, tar, ar) without filling in the holes. 

Dptr pointers returned by these subroutines point into static storage that is changed by subsequent calls. 
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The sum of the sizes of a key/content pair must not exceed the internal block size (currently 1024 bytes). 
Moreover all key/content pairs that hash together must fit on a single block. Store will return an error in 
the event that a disk block fills with inseparable data. 

Delete does not physically reclaim file space, although it does make it available for reuse. 

The order of keys presented by firstkey and nextkey depends on a hashing function, not on anything 
interesting. 

There are no interlocks and no reliable cache flushing; thus concurrent updating and reading is risky. 
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NAME 

itom, madd, msub, mult, mdiv, min, mout, pow, gcd, rpow - multiple precision integer arithmetic 
SYNOPSIS 

#include <mp.h> 

madd(a, b, c) 

MINT *a, *b, *c; 

msub(a, b, c) 

MINT *a, *b, *c; 

mult(a, b, c) 

MINT *a, *b, *c; 

mdiv(a, b, q, r) 

MINT *a, *b, *q, *r; 

min(a) 

MINT *a; 

mout(a) 

MINT *a; 

pow(a, b, c, d) 

MINT *a, *b, *c, *d; 

gcd(a, b, c) 

MINT *a, *b, *c; 

rpow(a, n, b) 

MINT *a, *b; 
short n; 

msqrt(a, b, r) 

MINT *a, *b, *r; 

sdiv(a, n, q, r) 

MINT *a, ♦q; 
short n, *r; 

MINT *itom(n) 
short n; 

DESCRIPTION 

These routines perform arithmetic on integers of arbitrary length. The integers are stored using the defined 
type MINT . Pointers to a MINT should be initialized using the function itom, which sets the initial value to 
n. After that space is managed automatically by the routines. 

Madd, msub and mult assign to their third arguments the sum, difference, and product, respectively, of their 
first two arguments. Mdiv assigns the quotient and remainder, respectively, to its third and fourth argu- 
ments. Sdiv is like mdiv except that the divisor is an ordinaiy integer. Msqrt produces the square root and 
remainder of its first argument. Rpow calculates a raised to the power b, while pow calculates this reduced 
modulo m. Min and mout do decimal input and output. 

Use the -Imp loader option to obtain access to these functions. 

DIAGNOSTICS 

Illegal operations and running out of memory produce messages and core images. 

FILES 
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/usr/lib/Iibmp.a 
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NAME 

openpl, erase, label, line, circle, arc, move, cont, point, linemod, space, closepl - graphics interface 
SYNOPSIS 

openpI() 

eraseO 

label(s) 
char s[]; 

line(xl, yl, x2, y2) 

circle(x, y, r) 

arc(x, y, xO, yO, xl, yl) 

move(x, y) 

cont(x, y) 

point(x, y) 

linemod(s) 
char s[]; 

space(xO, yO, xl, yl) 
closeplO 
DESCRIPTION 

These subroutines generate graphic output in a relatively device-independent manner. See plot (5) for a 
description of their effect. Openpl must be used before any of the others to open the device for writing. 
Closepl flushes the output. 

String arguments to label and linemod are null-terminated, and do not contain newlines. 

Various flavors of these functions exist for different output devices. They are obtained by the following 
ld(l) options: 

-Iplot device-independent graphics stream on standard output for plot (IG) filters 

-1300 GSI 300 terminal 

-1300s GSI 300S terminal 

-1450 DASI 450 terminal 

-14014 Tektronix 4014 terminal 

SEE ALSO 

plot(5), plot(lG), graph(lG) 

FILES 

/usr/lib/libplot.a 

/usr/lib/lib300.a 

/usr/lib/lib300s.a 

/usr/lib/lib450.a 

/usr/lib/lib4014.a 
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NAME 

tgetent, tgetnum, tgetflag, tgetstr, tgoto, tputs - terminal independent operation routines 

SYNOPSIS 

char PC; 
char *BC; 
char *UP; 
short ospeed; 

tgetent(bp, name) 
char *bp, *name; 

tgetnum(id) 
char *id; 

tgetflag(id) 
char *id; 

char * 

tgetstr(id, area) 
char *id, **area; 

char * 

tgoto(cm, destcol, destline) 
char *cm; 

tputs(cp, affcnt, outc) 
register char *cp; 
int affcnt; 
int (*outc)(); 

DESCRIPTION 

These functions extract and use capabilities from the terminal capability data base termcap ( 5). These are 
low level routines; see curses (iX) for a higher level package. 

Tgetent extracts the entry for terminal name into the buffer, with the current size of the tty (usually a win- 
dow). This allows pre-SunWindows programs to run in a window of arbitrary size. bp. Bp should be a 
character buffer of size 1024 and must be retained through all subsequent calls to tgetnum, tgetflag, and 
tgetstr. Tgetent returns -1 if it cannot open the termcap file, 0 if the terminal name given does not have an 
entry, and 1 if all goes well. It will look in the environment for a TERMCAP variable. If found, and the 
value does not begin with a slash, and the terminal type name is the same as the environment string TERM, 
the TERMCAP string is used instead of reading the termcap file. If it does begin with a slash, the string is 
used as a path name rather than letcltermcap. This can speed up entry into programs that call tgetent, as 
well as to help debug new terminal descriptions or to make one for your terminal if you can’t write the file 
letcltermcap. Note that if the window size changes, the "lines" and "columns”entries in bp are no longer 
correct. See the Sunwindows Reference Manual for details regarding [how to handle] this. 

Tgetnum gets the numeric value of capability id, returning -1 if is not given for the terminal. Tgetflag 
returns 1 if the specified capability is present in the terminal’s entry, 0 if it is not Tgetstr gets the string 
value of capability id, placing it in the buffer at area, advancing the area pointer. It decodes the abbrevia- 
tions for this field described in termcap (5), except for cursor addressing and padding information. 

Tgoto returns a cursor addressing string decoded from cm to go to column destcol in line destline. It uses 
the external variables UP (from the up capability) and BC (if be is given rather than bs) if necessary to 
avoid placing \n, “D or A @ in the returned string. (Programs which call tgoto should be sure to turn off the 
XTABS bit(s), since tgoto may now output a tab. Note that programs using termcap should in general turn 
off XTABS anyway since some terminals use control I for other functions, such as nondestructive space.) 
If a % sequence is given which is not understood, then tgoto returns “OOPS”. 
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Tputs decodes the leading padding information of the string cp; affcnt gives the number of lines affected by 
the operation, or 1 if this is not applicable, outc is a routine which is called with each character in turn. The 
external variable o speed should contain the encoded output speed of the terminal as described in tty (A). 
The external variable PC should contain a pad character to be used (from the pc capability) if a null ( A @) is 
inappropriate. 

FILES 

/usr/lib/libtermcap.a -ltermcap library 
/etc/termcap data base 

SEE ALSO 

ex(l), curses(3X), tty(4), termcap(5) 
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NAME 

intro - introduction to special files and hardware support 
DESCRIPTION 

This section describes device interfaces (drivers) in the operating system for disks, tapes, serial communi- 
cations, high-speed network communications, and other devices such as mice, frame buffers and windows. 
The section is divided into a few subsections: 

° Sun-specific drivers are grouped in ‘4S’. 

• Protocol families are grouped in ‘4F’ . 

- Protocols and raw interfaces are treated in ‘4P’. 

0 Network interfaces are grouped in ‘4N’. 

The operating system can be built with or without many of the drivers listed here. For most of them, the 
SYNOPSIS section of the manual page gives the syntax of the line to include in a kernel configuration file 
if you wish to include the driver in a system. See config(8) for a description of this process. 

Several manual pages will contain SYNOPSIS sections specific to the Sun-2 and Sun-3 architectures. 
Where a SYNOPSIS section appears without any specific architecture against it, it applies to both the Sun- 
2 and Sun-3 architectures. Where a SYNOPSIS section appears with only one specific architecture against 
it, it applies only to that specific architecture. 

The pages for most drivers also include a DIAGNOSTICS section listing error messages the driver may 
produce. These messages appear on the system console, and also in the system error log file 
lusrladm/messages . 

DEVICES ALWAYS PRESENT 

Drivers which are present in every kernel include a driver for the paging device, drum (4); drivers for 
accessing physical, virtual, and I/O space, mem(4S)\ and drivers for the data sink, null (4). 

COMMUNICATIONS DEVICES 

Communications lines are most often used with the terminal driver described in tty (4). The terminal driver 
runs on communications lines provided either by a communications driver such as mti{ 4S) or z.s(4S) or by 
a virtual terminal. The virtual terminal may be provided either by the Sun console monitor, cons (4S), or by 
a true pseudo-terminal, pty(4), used in applications such as windowing or remote networking. 

MAGNETIC TAPE DEVICES 

Magnetic tapes all provide the interface described in mtio (4). Tape devices for the Sun include ar(4S), 
fm(4S), st(4S), andx/(4S). 

DISK DEVICES 

Disk controllers provide standard block and raw interfaces, as well as a set of iocd’s defined in dkio (4S), 
which support getting and setting disk geometry and partition information. Drivers available for the Sun 
include xy(4S), ip(4S), and ^(4S). 

PROTOCOL FAMILIES 

The operating system supports one or more protocol families for local network communications. The only 
complete protocol family in this version of the system is the Internet protocol family; see inet{ 4F). Each 
protocol family provides basic services — packet fragmentation and reassembly, routing, addressing, and 
basic transport — to each protocol implementation. A protocol family is normally composed of a number 
of protocols, one per socket { 2) type. A protocol family is not required to support all socket types. 

The primary network support is for the Internet protocol family described in inet(4¥). Major protocols in 
this family include the Internet Protocol, i/?(4P), describing the universal datagram format, the stream 
Transmission Control Protocol tcp{ 4P), the User Datagram Protocol udp (4P), the Address Resolution Pro- 
tocol arp( 4P), the Internet Control Message Protocol icmp (4P), and die Network Interface Tap nit( 4P). 
The primary network interface is for the 10 Megabit Ethernet; see ec(4S), ie(4S), and /e(4S). A software 
loopback interface, lo(4) also exists. General properties of these (and all) network interfaces are described 
in i/(4N). 
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The general support in the system for local network routing is described in routing {Any, these facilities 
apply to all protocol families. 

MISCELLANEOUS DEVICES 

Miscellaneous devices include color frame buffers cg*(4S), monochrome frame buffers bw*{AS), the con- 
sole frame buffer fb (4S), the graphics processor interface gpone( 4S), the console mouse mouse {AS), and 
the window devices win(AS). 


GENERAL IOCTL CALLS 

In general, ioctl calls relating to a specific device are mentioned with the description for that device. There 
are however a bunch of ioctl calls that apply to files in general. These are described here. The form of the 
ioctl call for file control is: 

#include <sys/ioctl.h> 
ioctl(fd, request, argp) 
int fd, request; 
int *argp; 

FIOCLEX Set exclusive use on the file descriptor specified by fd. The argp argument is not used 
in this call. 

FIONCLEX Remove exclusive use on the file descriptor specified by fd. The argp argument is not 
used in this call. 


FIONREAD 

FIONBIO 

FIOASYNC 

FIOSETOWN 

FIOGETOWN 


Returns in the long integer whose address is argp the number of immediately readable 
characters from whatever the descriptor specified by fd. refers to. This works for files, 
pipes, and terminals. 

Set or clear non-blocking I/O. If the value pointed to by argp is a 1 (one) the descriptor 
is set for non-blocking I/O. If the value pointed to by argp is a 0 (zero) the descriptor is 
cleared for non-blocking I/O. 

Set or clear asynchronous I/O. If the value pointed to by argp is a 1 (one) the descriptor 
is set for asynchronous I/O. If the value pointed to by argp is a 0 (zero) the descriptor is 
cleared for asynchronous I/O. 

Set the process-group ID that will subsequently receive SIGIO or SIGURG signals for this 
descriptor. 

Get the process-group ID that is receiving SIGIO or SIGURG signals for this descriptor. 


276 


Last change: 25 July 1985 


Sun Release 3.0 



AR(4S) 


SPECIAL FILES 


AR(4S) 


NAME 

ar - Archive 1/4 inch Streaming Tape Drive 
SYNOPSIS — SUN-2 

device arO at mbio ? csr 0x200 priority 3 
device arl at mbio ? csr 0x208 priority 3 

DESCRIPTION 

The Archive tape controller is a Sun ‘QIC-IP interface to an Archive streaming tape drive. It provides a 
standard tape interface to the device, see mtio (4), with some deficiencies listed under BUGS below. 

The maximum blocksize for the raw device is limited only by available memory. 

FI LES 

/dev/rar* 

/dev/nrar* non-rewinding 

SEE ALSO 

mtio(4) 

Archive Intelligent Tape Drive Theory of Operation, Archive Corporation (Sun 8000-1058-01) 

Archive Product Manual (Sidewinder 1/4" Streaming Cartridge Tape Drive) (Sun 800-0628-01) 

Sun 1/4" Tape Interface - User Manual (Sun 800-0415-01) 

DIAGNOSTICS 

ar*: would not initialize. 

"ar*: already open." 

The tape can be open by only one process at a time, 
ar*: no such drive, 
ar*: no cartridge in drive, 
ar*: cartridge is write protected, 
ar: interrupt from unitialized controller %x. 
ar*: many retries, consider retiring this tape, 
ar*: %b error at block# %d punted, 
ar*: %b error at block# %d. 
ar: giving up on Rdy, try again. 

BUGS 

The tape cannot reverse direction so the BSF and BSR ioctls are not supported. 

The FSR ioctl is not supported. 

The system will hang if the tape is removed while running. 

When using the raw device, the number of bytes in any given transfer must be a multiple of 512 bytes. If it 
is not, the device driver returns an error. 

The driver will only write an end of file mark on close if the last operation was a write, without regard for 
the mode used when opening the file. This will cause empty files to be deleted on a raw tape copy opera- 
tion. 
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NAME 

arp - Address Resolution Protocol 

SYNOPSIS 

pseudo-device ether 

DESCRIPTION 

ARP is a protocol used to dynamically map between DARPA Internet and lOMb/s Ethernet addresses. It is 
used by all the lOMb/s Ethernet interface drivers. 

ARP caches Intemet-Ethemet address mappings. When an interface requests a mapping for an address not 
in the cache, ARP queues the message which requires the mapping and broadcasts a message on the associ- 
ated network requesting the address mapping. If a response is provided, the new mapping is cached and 
any pending messages are transmitted. ARP will queue at most one packet while waiting for a mapping 
request to be responded to; only the most recently “transmitted” packet is kept. 

To enable communications with systems which do not use ARP, ioctls are provided to enter and delete 
entries in the Intemet-to-Ethemet tables. Usage: 

#include <sys/ioctl.h> 

#include <sys/socket.h> 

#include <net/if.h> 
struct arpreq arpreq; 


ioctl(s, SIOCSARP, (caddr_t)&arpreq); 
iocti(s, SIOCGARP, (caddr_t)&arpreq); 
ioctl(s, SIOCDARP, (caddr_t)&arpreq); 


Each ioctl takes the same structure as an argument. SIOCSARP sets an ARP entry, SIOCGARP gets an 
ARP entry, and SIOCDARP deletes an ARP entry. These ioctls may be applied to any socket descriptor s, 
but only by the super-user. The arpreq structure contains: 

I* 

* ARP ioctl request 
*/ 


struct arpreq { 

struct sockaddr arp_pa; 
struct sockaddr arpha; 
int aipflags; 

}; 

/* arpflags field values */ 

#define ATFCOM 2 

#define ATF_PERM 4 

#define ATF PUBL 8 


I* protocol address */ 
/* hardware address */ 
I* flags */ 


/* completed entry (arp_ha valid) */ 
/* permanent entry */ 

/* publish (respond for other host) */ 


The address family for the arp _pa sockaddr must be AFJNET; for the arp ha sockaddr it must be 
AFUNSPEC. The only flag bits which may be written are ATF PERM and ATFPUBL. ATF PERM 
causes the entry to be permanent if the ioctl call succeeds. The peculiar nature of the ARP tables may cause 
the ioctl to fail if more than 4 (permanent) Internet host addresses hash to the same slot. ATF PUBL 
specifies that the ARP code should respond to ARP requests for the indicated host coming from other 
machines. This allows a Sun to act as an "ARP server" which may be useful in convincing an ARP-only 
machine to talk to a non-ARP machine. 


ARP watches passively for hosts impersonating the local host (that is, a host which responds to an ARP 
mapping request for the local host’s address). 

DIAGNOSTICS 

duplicate IP address!! sent from ethernet address: %x:%x:%x:%x:%x:%x. ARP has discovered 
another host on the local network which responds to mapping requests for its own Internet address. 
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SEE ALSO 

ec(4S), ie(4S), inet(4F), arp(8C), ifconfig(8C) 

An Ethernet Address Resolution Protocol, RFC826, Dave Plummer, MIT (Sun 800-1059-01) 

BUGS 

ARP packets on the Ethernet use only 42 bytes of data, however, the smallest legal Ethernet packet is 60 
bytes (not including CRC). Some systems may not enforce the minimum packet size, others will. 
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NAME 

bk - line discipline for machine-machine communication 
SYNOPSIS 

pseudo-device bk 

DESCRIPTION 

This line discipline provides a replacement for the tty driver tty (4) when high speed output to and espe- 
cially input from another machine is to be transmitted over an asynchronous communications line. The dis- 
cipline was designed for use by a (now obsolete) store-and-forward local network running over serial lines. 
It may be suitable for uploading of data from microprocessors into the system. If you are going to send 
data over asynchronous communications lines at high speed into the system, you must use this discipline, 
as the system otherwise may detect high input data rates on terminal lines and disable the lines; in any case 
the processing of such data when normal terminal mechanisms are involved saturates the system. 

The line discipline is enabled by a sequence: 

#include <sgtty.h> 

int ldisc = NETLDISC, fildes; ... 

ioctI(fildes, TIOCSETD, &ldisc); 

A typical application program then reads a sequence of lines from the terminal port, checking header and 
sequencing information on each line and acknowledging receipt of each line to the sender, who then 
ttansmits another line of data. Typically several hundred bytes of data and a smaller amount of control 
information will be received on each handshake. 

The old standard teletype discipline can be restored by doing: 

ldisc = OTTYDISC; 
ioctl(fildes, TIOCSETD, &ldisc); 

While in networked mode, normal teletype output functions take place. Thus, if an 8 bit output data path is 
desired, it is necessary to prepare the output line by putting it into RAW mode using ioctl(2). This must be 
done before changing the discipline with TIOCSETD, as most ioctl( 2) calls are disabled while in network 
line-discipline mode. 

When in network mode, input processing is very limited to reduce overhead. Currently the input path is 
only 7 bits wide, with newline the only character terminating an input record. Each input record must be 
read and acknowledged before the next input is read as the system refuses to accept any new data when 
there is a record in the buffer. The buffer is limited in length, but the system guarantees to always be wil- 
ling to accept input resulting in 512 data characters and then the terminating newline. 

User level programs should provide sequencing and checksums on the information to guarantee accurate 
data transfer. 

SEE ALSO 

tty(4) 
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NAME 

bwone - Sun-1 black and white frame buffer 
SYNOPSIS — SUN-2 

device bwoneO at mbmem ? csr OxcOOOO priority 3 
DESCRIPTION 

The bwone interface provides access to Sun-1 black-and-white graphics controller boards. It supports the 
FBIOGTYPE ioctl which programs can use to determine the characteristics of the display device; see 
fbio( 4S) 

It supports the FBIOGPIXRECT ioctl which allows SunWindows to be mn on it; seefbio(4S) 

Reading or writing to the frame buffer is not allowed - you must use the mmap( 2) system call to map the 
board into your address space. 

FILES 

/dev/bwone[0-9] 

SEE ALSO 

mmap(2), fb(4S), fbio(4S) 

Sun 1024 Video Board - User Manual (Sun 800-0420) 

BUGS 

Use of vertical-retrace interrupts is not supported. 
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NAME 

bwtwo - Sun-3/Sun-2 black and white frame buffer 
SYNOPSIS — SUN-3 

device bwtwoO at obmem 1 csr OxffOOOOOO priority 4 
device bwtwoO at obmem 2 csr 0x100000 priority 4 

The first synopsis line given above should be used to generate a kernel for a Sun-3/160; the second, for a 
Sun-3/7 5M. 

SYNOPSIS — SUN-2 

device bwtwoO at obmem 1 csr 0x700000 priority 4 
device bwtwoO at obio 2 csr 0x0 priority 4 

The first synopsis line given above should be used to generate a kernel for a Sun-2/120 or Sun-2/170; the 
second, for a Sun-2/50 or Sun-2/160. 

DESCRIPTION 

The bwtwo interface provides access to Sun Monochrome Video Controller boards. 

bwtwo supports the FBIOGTYPE iocd, which programs may use to determine the characteristics of the 
display device, and supports the FBIOGPIXRECT ioctl, which allows SunWindows to be run on it (see 
fbio( 4S)). 

If flags 0x1 is specified, copy memory will be used in the frame buffer if applicabale. Copy memory 
makes certain frame buffer faster at the expense of 128K bytes of memory. 

Reading or writing to the frame buffer is not allowed - you must use the mmap( 2) system call to map the 
board into your address space. 

FILES 

/dev/bwtwo[0-9] 

SEE ALSO 

mmap(2), fb(4S), fbio(4S) 

BUGS 

Use of vertical-retrace interrupts is not supported. 
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NAME 

cgone - Sun-1 color graphics interface 
SYNOPSIS — SUN-2 

device cgoneO at mbmem ? csr OxecOOO priority 3 
DESCRIPTION 

The cgone interface provides access to the Sun-1 color graphics controller board, which is normally sup- 
plied with a 13" or 19" RS170 color monitor. It provides the standard frame buffer interface as defined in 
fbio(AS). 

It supports the FBIOGPIXRECT ioctl which allows SunWindows to be run on it; s eefbio(4S) 

The hardware consumes 16 kilobytes of Multibus memory space. The board starts at standard addresses 
OxE8000 or OxECOOO. The board must be configured for interrupt level 3. 

FILES 

/dev/cgone[0-9] 

SEE ALSO 

mmap(2), fbio(4S) 

Sun Color Video Board User’s Manual (Sun 8000-0398, Rev B) 

Barco GD33 Color Display 120V AC Operation Instructions (13") (Sun 800-1002-01) 

Barco Color Display CD 252 120/220VAC Operation Guide (19") (Sun 800-1003-01) 

BUGS 

Use of color board vertical-retrace interrupts is not supported. 
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NAME 

cgtwo - Sun-3/Sun-2 color graphics interface 
SYNOPSIS — SUN-3 

cgtwoO at vme24dl6 ? csr 0x400000 priority 3 
SYNOPSIS — SUN-2 

cgtwoO at vme24 ? csr 0x400000 priority 3 
DESCRIPTION 

The cgtwo interface provides access to the Sun-3/Sun-2 color graphics controller board, which is normally 
supplied with a 19” 60 Hz non-interlaced color monitor. It provides the standard frame buffer interface as 
defined in fbio( 4S). 

The hardware consumes 4 megabytes of VME bus address space. The board starts at standard address 
0x400000. The board must be configured for interrupt level 3. 

FILES 

/dev/cgtwo[0-9] 

SEE ALSO 

mmap(2), fbio(4S) 

User’s Manual for the Sun-2 Color Graphics Board. 
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NAME 

cons - console driver and terminal emulator for the Sun workstation 
SYNOPSIS 

None; included in standard system. 

DESCRIPTION 

Cons is an indirect driver for the Sun workstation console, which implements a standard UNIX system ter- 
minal. Cons is implemented by calling the PROM resident monitor or other kernel UART drivers (zs(4S)) to 
perform I/O to and from the current system console, which is either a Sun frame buffer or an RS232 port 

When the Sun window system win (4S) is active, console input is directed through the window system 
rather than being read from the hardware console. 

An ioctl TIOCCONS may be applied to serial devices other than the console to route output which would 
normally appear on the console to the other devices instead. Thus, the window system does a TIOCCONS 
on a pseudo-terminal to route console output to the pseudo-terminal rather than routing output through the 
PROM monitor to the screen, since routing output through the PROM monitor destroys the integrity of the 
screen. 

ANSI STANDARD TERMINAL EMULATION 

The Sun Workstation’s PROM monitor provides routines that emulates a standard ANSI X3.64 terminal. 

Note that the VT100 also follows the ANSI X3.64 standard but both the Sun and the VT100 have nonstan- 
dard extensions to the ANSI X3.64 standard. The Sun terminal emulator and the VT100 are not compatible 
in any true sense. 

The Sun console displays 34 lines of 80 ASCII characters per line, with scrolling, (x, y) cursor addressabil- 
ity, and a number of other control functions. 

The Sun console displays a non-blinking block cursor which marks the current line and character position 
on the screen. ASCII characters between 0x20 (space) and 0x7E (tilde) inclusive are printing characters — 
when one is written to the Sun console (and is not part of an escape sequence), it is displayed at the current 
cursor position and the cursor moves one position to the right on the current line. If the cursor is already at 
the right edge of the screen, it moves to the first character position on the next line. If the cursor is already 
at the right edge of the screen on the bottom line, the Line-feed function is performed (see control-J 
below), which scrolls the screen up by one or more lines or wraps around, before moving the cursor to the 
first character position on the next line. 

Control Sequence Syntax 

The Sun console defines a number of control sequences which may occur in its input When such a 
sequence is written to the Sun console, it is not displayed on the screen, but effects some control function 
as described below, for example, moves the cursor or sets a display mode. 

Some of the control sequences consist of a single character. The notation 
control-X 

for some character X , represents a control character. 

Other ANSI control sequences are of the form 
ESC [ <params> <char> 

Spaces are included only for readability; these characters must occur in the given sequence without the 
intervening spaces. 

ESC represents the ASCII escape character (ESC, control-!, OxlB). 

[ The next character is a left square bracket T (0x5B). 

<params> 

are a sequence of zero or more decimal numbers made up of digits between 0 and 9, separated by 
semicolons. 

<char> represents a function character, which is different for each control sequence. 
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Some examples of syntactically valid escape sequences are (again, ESC represent the single ASCII character 
‘Escape’): 

ESC [m select graphic rendition with default parameter 

ESC [7m select graphic rendition with reverse image 

ESC [ 33;54H set cursor position 

ESC [ 123;456;0;;3;B move cursor down 

Syntactically valid ANSI escape sequences which are not currently interpreted by the Sun console are 
ignored. Control characters which are not currently interpreted by the Sun console are also ignored. 

Each control function requires a specified number of parameters, as noted below. If fewer parameters are 
supplied, the remaining parameters default to 1, except as noted in the descriptions below. 

If more than the required number of parameters is supplied, only the last n are used, where n is the number 
required by that particular command character. Also, parameters which are omitted or set to zero are reset 
to the default value of 1 (except as noted below). 

Consider, for example, the command character M which requires one parameter. ESC[;M and ESC[0M 
and ESC[M and ESC[23;15;32;1M are all equivalent to ESC[1M and provide a parameter value of 1. Note 
that ESC[;5M (interpreted as ‘ESC[5M’) is not equivalent to ESC[5;M (interpreted as ‘ESC[5;1M’) which 
is ultimately interpreted as ‘ESC [ 1M’). 

In the syntax descriptions below, parameters are represented as “#’ or ‘#1;#2’. 

ANSI Control Functions 

The following paragraphs specify the ANSI control functions implemented by the Sun console. Each 
description gives: 

• the control sequence syntax 

• the hex equivalent of control characters where applicable 

• the control function name and ANSI or Sun abbreviation (if any). 

• description of parameters required, if any 

• description of the control function 

• for functions which set a mode, the initial setting of the mode. The initial settings can be restored with 
the SUNRESET escape sequence. 

Control Character Functions 
control-G (0x7) Bell (BEL) 

The Sun Workstation Model 100 and 100U is not equipped with an audible bell. It ‘rings the bell’ 
by flashing the entire screen. The Sun-2 models have an audible bell which beeps. The window 
system flashes the window. 

control-H (0x8) Backspace (BS) 

The cursor moves one position to the left on the current line. If it is already at the left edge of the 
screen, nothing happens. 

control-I (0x9) Tab (TAB) 

The cursor moves right on the current line to the next tab stop. The tab stops are fixed at every 
multiple of 8 columns. If the cursor is already at the right edge of the screen, nothing happens; 
otherwise the cursor moves right a minimum of one and a maximum of eight character positions. 

control-J (OxA) Line-feed (LF) 

The cursor moves down one line, remaining at the same character position on the line. If the cur- 
sor is already at the bottom line, the screen either scrolls up or ‘wraps around’ depending on the 
setting of an internal variable 5 (initially 1) which can be changed by the ESC [r control sequence. 
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If S is greater than zero, the entire screen (including the cursor) is scrolled up by S lines before 
executing the Line-feed. The top S lines scroll off the screen and are lost. S new blank lines scroll 
onto the bottom of the screen. After scrolling, the line-feed is executed by moving the cursor 
down one line. 

If S is zero, ‘wrap-around’ mode is entered. ‘ESC [ 1 r’ exits back to scroll mode. If a linefeed 
occurs on the bottom line in wrap mode, the cursor goes to the same character position in the top 
line of the screen. When any linefeed occurs, the line that the cursor moves to is cleared. This 
means that no scrolling occurs. Wrap-around mode is not implemented in the window system. 

The screen scrolls as fast as possible depending on how much data is backed up awaiting printing. 
Whenever a scroll must take place and the console is in normal scroll mode (‘ESC [ 1 r’), it scans 
the rest of the data awaiting printing to see how many linefeeds occur in it This scan stops when 
any control character from the set {VT, FF, SO, SI, DLE, DC1, DC2, DC3, DC4, NAK, SYN, 
ETB, CAN, EM, SUB, ESC, FS, GS, RS, US} is found. At that point the screen is scrolled by N 
lines (N at least 1) and processing continues. The scanned text is still processed normally to fill in 
the newly created lines. This results in much faster scrolling with scrolling as long as no escape 
codes or other control characters are intermixed with the text 

See also the discussion of the ‘Set scrolling’ (ESC [r) control funtion below. 

control-K (OxB) Reverse Line-feed 

The cursor moves up one line, remaining at the same character position on the line. If the cursor 
is already at the top line, nothing happens. 

control-L (OxC) Form-feed (FF) 

The cursor is postioned to the Home position (upper-left comer) and the entire screen is cleared. 
control-M (OxD) Return (CR) 

The cursor moves to the leftmost character position on the current line. 

Escape Sequence Functions 
control-[ (OxlB) Escape (ESC) 

This is the escape character. Escape initiates a multi-character control sequence. 

ESC [ #@ Insert Character (ICH) 

Takes one parameter, # (default 1). Inserts # spaces at the current cursor position. The tail of the 
current line starting at the current cursor position inclusive is shifted to the right by # character 
positions to make room for the spaces. The rightmost # character positions shift off the line and 
are lost. The position of the cursor is unchanged. 

ESC [ #A Cursor Up (CUU) 

Takes one parameter, # (default 1). Moves the cursor up # lines. If the cursor is fewer than # 
lines from die top of the screen, moves the cursor to the topmost line on the screen. The character 
position of the cursor on the line is unchanged. 

ESC [ #B Cursor Down (CUD) 

Takes one parameter, # (default 1). Moves the cursor down # lines. If the cursor is fewer than # 
lines from the bottom of the screen, move the cursor to the last line on the screen. The character 
position of the cursor on the line is unchanged. 

ESC [ #C Cursor Forward (CUF) 

Takes one parameter, # (default 1). Moves the cursor to the right by # character positions on the 
current line. If the cursor is fewer than # positions from the right edge of the screen, moves the 
cursor to the rightmost position on the current line. 

ESC [ #D Cursor Backward (CUB) 

Takes one parameter, # (default 1). Moves the cursor to the left by # character positions on the 
current line. If the cursor is fewer than # positions from the left edge of the screen, moves the 
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cursor to the leftmost position on the current line. 

ESC [ #E Cursor Next Line (CNL) 

Takes one parameter, # (default 1). Positions the cursor at the leftmost character position on the 
#-th line below the current line. If the current line is less than # lines from the bottom of the 
screen, postions the cursor at the leftmost character position on the bottom line. 

ESC [#1 ;#2f Horizontal And Vertical Position (HVP) 
or 

ESC [#1 ;#2H Cursor Position (CUP) 

Takes two parameters, #1 and #2 (default 1, 1). Moves the cursor to the #2-th character position 
on the #l-th line. Character positions are numbered from 1 at the left edge of the screen; line 
positions are numbered from 1 at the top of the screen. Hence, if both parameters are omitted, the 
default action moves the cursor to the home position (upper left comer). If only one parameter is 
supplied, the cursor moves to column 1 of the specified line. 

ESC [ J Erase in Display (ED) 

Takes no parameters. Erases from the current cursor position inclusive to the end of the screen. 
In other words, erases from the current cursor position inclusive to the end of the current line and 
all lines below the current line. The cursor position is unchanged. 

ESC [K Erase in Line (EL) 

Takes no parameters. Erases from the current cursor position inclusive to the end of the current 
line. The cursor position is unchanged. 

ESC [ #L Insert Line (IL) 

Takes one parameter, # (default 1). Makes room for # new lines starting at the current line by 
scrolling down by # lines the portion of the screen from the current line inclusive to the bottom. 
The # new lines at the cursor are filled with spaces; the bottom # lines shift off the bottom of the 
screen and are lost. The position of the cursor on the screen is unchanged. 

ESC [ #M Delete Line (DL) 

Takes one parameter, # (default 1). Deletes # lines beginning with the current line. The portion 
of the screen from the current line inclusive to the bottom is scrolled upward by # lines. The # 
new lines scrolling onto the bottom of the screen are filled with spaces; the # old lines beginning at 
the cursor line are deleted. The position of the cursor on the screen is unchanged. 

ESC [ #P Delete Character (DCH) 

Takes one parameter, # (default 1). Deletes # characters starting with the current cursor position. 
Shifts to the left by # character positions the tail of the current line from the current cursor posi- 
tion inclusive to the end of the line. Blanks are shifted into the rightmost # character positions. 
The position of the cursor on the screen is unchanged. 

ESC [ #m Select Graphic Rendition (SGR) 

Takes one parameter, # (default 0). Note that, unlike most escape sequences, the parameter 
defaults to zero if omitted. Invokes the graphic rendition specified by the parameter. All follow- 
ing printing characters in the data stream are rendered according to the parameter until the next 
occurrence of this escape sequence in the data stream. Currently only two graphic renditions are 
defined: 

0 Normal rendition. 

7 Negative (reverse) image. 

Negative image displays characters as white-on-black if the screen mode is currently black-on 
white, and vice-versa. Any non-zero value of # is currently equivalent to 7 and selects the nega- 
tive image rendition. 

ESC [p Black On White (SUNBOW) 

Takes no parameters. Sets the screen mode to black-on-white. If the screen mode is already 
black-on-white, has no effect. In this mode spaces display as solid white, other characters as 
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black-on-white. The cursor is a solid black block. Characters displayed in negative image rendi- 
tion (see ‘Select Graphic Rendition’ above) is white-on-black in this mode. This is the initial set- 
ting of the screen mode on reset 

ESC ( q White On Black (SUNWOB) 

Takes no parameters. Sets the screen mode to white-on-black. If the screen mode is already 
white-on-black, has no effect. In this mode spaces display as solid black, other characters as 
white-on-black. The cursor is a solid white block. Characters displayed in negative image rendi- 
tion (see ‘Select Graphic Rendition’ above) is black-on-white in this mode. The initial setting of 
the screen mode on reset is the alternative mode, black on white. 

ESC (#r Set scrolling (SUNSCRL) 

Takes one parameter, # (default 0). Sets to # an internal register which determines how many lines 
the screen scrolls up when a line-feed function is performed with the cursor on the bottom line. A 
parameter of 2 or 3 introduces a small amount of ‘jump’ when a scroll occurs. A parameter of 34 
clears the screen rather than scrolling. The initial setting is 1 on reset 

A parameter of zero initiates ‘wrap mode’ instead of scrolling. In wrap mode, if a linefeed occurs 
on the bottom line, the cursor goes to the same character position in the top line of the screen. 
When any linefeed occurs, the line that the cursor moves to is cleared. This means that no scrol- 
ling ever occurs. ‘ESC [ 1 r’ exits back to scroll mode. 

For more information, see the description of the Line-feed (control-J) control function above. 

ESC [ s Reset terminal emulator (SUNRESET) 

Takes no parameters. Resets all modes to default, restores current font from PROM. Screen and 
cursor position are unchanged. 

4014 TERMINAL EMULATION 

The PROM monitor for Sun models 100U and 150U provides routines the Sun Workstation with the capa- 
bility to emulate a subset of the Tektronix 4014 terminal. This feature does not exist in Sun-2 PROMs and 
will be removed from models 100U and 150U in future Sun releases. Tektool(\) provides Tektronix 4014 
terminal emulation and should be used instead of relying on the capabilities of the PROM monitor. 

FILES 

/dev/console 

/dev/ttya alternate console (serial port) 

SEE ALSO 

oct(4S), tty(4), zs(4S), tektool(l) 

ANSI Standard X3.64, ‘Additional Controls for Use with ASCII’, Secretariat: CBEMA, 1828 L St., N.W., 
Washington, D.C. 20036. 

BUGS 

TIOCCONS should be restricted to the owner of /dev/console. 
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NAME 

des - DES encryption chip interface 

SYNOPSIS — SUN-3 

desO at obio ? csr OxlcOOOO 

#include <sys/des.h> 

SYNOPSIS — SUN-2 

desO at virtual ? csr 0xeel800 

#include <sys/des.h> 

DESCRIPTION 

The des driver provides a high level interface to the AmZ8068 Data Ciphering Processor, a hardware 
implementation of the NBS Data Encryption Standard. 

The high level interface provided by this driver is hardware independent and could be shared by future 
drivers in other systems. The driver implements a number of minor devices (currently, ten); each of these 
is an exclusive-use device which maintains the state of one encryption channel. The correct way to obtain 
a file descriptor for a DES channel is to iterate over the possible DES devices ( Idev/desO through 
Idevldes9) until either an open succeeds or an error other than EBUSY is indicated. 

The interface allows access to two modes of the DES algorithm: Electronic Code Book (ECB) and Cipher 
Block Chaining (CBC). All access to the DES driver is through ioctl (2) calls rather than through reads and 
writes; all encryption is done in-place in the user’s buffers. The ioctls provided are: 

DESIOCSETKEY 

This command sets the encryption mode, direction (encrypt or decrypt), and key. The argument to this 
call is struct deskey as defined in <sys/des.h>. 

DESIOCGETKEY 

This call returns the current key and modes (struct deskey) for the encryption channel. 
DESIOCSETIVEC 

This call sets the "initialization vector" used by the Cipher Block Chaining mode. This 8 byte value is 
XORed with the each 8 byte chunk of data before the beginning of an ecryption operation and replaced 
by the output of the operation. The argument of the ioctl is the address of a struct desivec which con- 
tains the 8 byte value. 

DESIOCGETTVEC 

This call returns the current value of the initialization vector. 

DESIOCCHUNK 

This call invokes an encryption operation on a single 8 byte data "chunk”. It is expected that this call 
would be most useful in ECB mode. The argument of the ioctl is the address of the 8 bytes to be 
encrypted or decrypted. 

DESIOCBLOCK 

This call encrypts/decrypts an entire buffer of data, whose address and length are passed in the struct 
desblock addressed by the argument. The length must be a multiple of 8 bytes. 

FILES 

/dev/des? 

SEE ALSO 

des(l) 

Federal Information Processing Standards Publication 46 
AmZ8068 DCP Product Description, Advanced Micro Devices 
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BUGS 

The AmZ8068 is not intended to be context-switchable. Hence, the driver uses only the most basic 
features of the chip (ECB mode) and maintains other state in software. 
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NAME 

dkio - generic disk control operations 
DESCRIPTION 

All Sun disk drivers support a set of ioctl’s for disk formattting and labelling operations. Basic to these 
ioctl’s are the definitions in <sun/dkio.h>: 

/* 

* Structures and definitions for disk io control commands 
*1 


/* Disk identification */ 
struct dk info { 

int dkictlr; 

/* controller address */ 

short dki unit; 


1* unit (slave) address */ 

short dkictype; 


1* controller type */ 

short dki flags; 


/* flags */ 

J > 

/* controller types */ 

#define DKC UNKNOWN 

0 


#define DKC SMD2180 

1 


#define DKC XY440 

4 


#define DKC DSD5215 

5 


#define DKC XY450 

6 


#define DKC SCSI 

7 



/* flags */ 

#define DKIBAD144 0x01 I* use DEC std 144 bad sector fwding *1 

#define DKI_MAPTRK 0x02 /* controller does track mapping */ 

#define DKIFMTTRK 0x04 /* formats only full track at a time */ 

#define DKI FMTVOL 0x08 /* formats only full volume at a time */ 

/* Definition of a disk’s geometry */ 
struct dkgeom { 

unsigned short dkg ncyl; I* # of data cylinders *1 

unsigned short dkg_acyl; /* # of alternate cylinders */ 

unsigned short dkgbcyl; /* cyl offset (for fixed head area) */ 

unsigned short dkg nhead; /* # of heads *1 

unsigned short dkg bhead; /* head offset (for Larks, etc.) */ 

unsigned short dkgnsect; I* # of sectors per track */ 

unsigned short dkg intrlv; I* interleave factor */ 

unsigned short dkgjjapl; /* gap 1 size */ 

unsigned short dkg j>ap2; /+ gap 2 size */ 

unsigned short dkg_extra[10]; /* for compatible expansion */ 

}; 

/* disk io control commands *1 

#define DKIOCGGEOM _IOR(d, 2, struct dk_geom) /* Get geometry */ 

#define DKIOCSGEOM _IOW(d, 3, struct dk_geom) /* Set geometry */ 

#define DKIOCGPART _IOR(d, 4, struct dk_map) /* Get partition info */ 

#define DKIOCSPART _IOW(d, 5, struct dk_map) /* Set partition info *1 

#define DKIOCINFO _IOR(d, 8, struct dk_info) /* Get info */ 
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The DKKX.GINFO ioctl returns a dk_info structure which tells the kind of the controller and attributes 
about how bad-block processing is done on the controller. The DKIOCGPART and DKIOCSPART get 
and set the ontroller’s current notion of the partition table for the disk (without changing the partition table 
on the disk itself), while the DKIOCGGEOM and DKIOCSGEOM ioctl’ s do similar things for the per- 
drive geon ry information. 

SEE ALSO 

ip(4S), sd(4S), xy(4S) 
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NAME 

drum - paging device 
SYNOPSIS 

None; included with standard system. 

DESCRIPTION 

This file refers to the paging device in use by the system. This may actually be a subdevice of one of the 
disk drivers, but in a system with paging interleaved across multiple disk drives it provides an indirect 
driver for the multiple drives. 

FILES 

/dev/drum 

BUGS 

Reads from the drum are not allowed across the interleaving boundaries. Since these only occur every 
•5Mbytes or so, and since the system never allocates blocks across the boundary, this is usually not a prob- 
lem. 


294 


Last change: 25 July 1985 


Sun Release 3.0 



EC(4S) 


SPECIAL FILES 


EC(4S) 


NAME 

ec - 3Com 10 Mb/s Ethernet interface 
SYNOPSIS — SUN-2 

device ecO at mbmem ? csr OxeOOOO priority 3 
device eel at mbmem ? csr 0xe2000 priority 3 

DESCRIPTION 

The ec interface provides access to a 10 Mb/s Ethernet network through a 3COM controller. For a general 
description of network interfaces see i/(4N). 

The hardware consumes 8 kilobytes of Multibus memory space. This memory is used for internal buffer- 
ing by the board. The board starts at standard addresses OxEOOOO or 0xE2000. The board must be 
configured for interrupt level 3. 

The interface software implements an exponential backoff algorithm when notified of a collision on the 
cable. 

The interface handles the Internet protocol family, with the interface address maintained in Internet format 
The Address Resolution Protocol arp( 4P) is used to map 32-bit Internet addresses used in inet(4F) to the 
48-bit addresses used on the Ethernet 

DIAGNOSTICS 

ec%d: Ethernet jammed. After 16 failed transmissions and backoffs using the exponential backoff algo- 
rithm, the packet was dropped. 

ec%d: can’t handle af%d. The interface was handed a message with addresses formatted in an unsuit- 
able address family ; the packet was dropped. 

SEE ALSO 

arp(4N), if(4N), inet(4F) 

3COM 3C400 Multibus Ethernet Controller Reference Manual (Sun 800-0398) 

BUGS 

The interface hardware is not capable of talking to itself, making diagnosis more difficult 
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NAME 

fb - driver for Sun console frame buffer 
SYNOPSIS 

None; included in standard system. 

DESCRIPTION 

Th e fb driver provides indirect access to a Sun graphics controller board. It is an indirect driver for the Sun 
workstation console’s frame buffer. At boot time, the workstation’s frame buffer device is determined 
from information from the Monitor Proms and set to be the one that fb will indirect to. The device driver 
for the console’s frame buffer must be configured into the kernel so that this indirect driver can access it. 

The idea behind this driver is that user programs can open a known device, query its characteristics and 
access it in a device dependent way, depending on the type. Fb redirects open (2), close (2), ioctl(2), and 
mmap(2) calls to the real frame buffer. All of the Sun frame buffers support the same general interface* 
see fbio(4S) 

FILES 

/dev/fb 
SEE ALSO 

fbio(4S), bwone(4S), bwtwo(4S), cgone(4S), cgtwo(4S), gpone(4S) 
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NAME 

fbio - general properties of frame buffers 
DESCRIPTION 

All of the Sun frame buffers support the same general interface. Each responds to a FBIOGTYPE ioctl ( 2) 
which returns information in a structure defined in <sunlfbio.h > : 


struct fbtype { 



int 

fbtype; 

/* as defined below */ 

int 

fbheight; 

/* in pixels *1 

int 

fbwidth; 

/* in pixels */ 

int 

fbdepth; 

/* bits per pixel */ 

int 

fbcmsize; 

1* size of color map (entries) */ 

int 

1: 

fbsize; 

1* total size in bytes */ 

#define FBTYPE SUN1BW 

0 

#define FBTYPE SUN1COLOR 

1 

#define FBTYPE SUN2BW 

2 

#define FBTYPE SUN2COLOR 

3 

#define FBTYPE SUN2GP 

4 


Each device has a FBTYPE which is used by higher-level software to determine how to perform raster-op 
and other functions. Each device is used by opening it, doing a FBIOGTYPE ioctl to see which frame 
buffer type is present, and thereby selecting the appropriate device-management routines. 

Full-fledged frame buffers (that is, those that run SunWindows), implement an FBIOGPIXRECT ioctl {2), 
which returns a pixrect. This call is made only from inside the kernel. The returned pixrect is used by 
win (4S) for cursor tracking and colormap loading. 

SEE ALSO 

mmap(2), bwone(4S), bwtwo(4S), cgone(4S), cgtwo(4S), gpone(4S), fb(4S), win(4S) 
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NAME 

gpone - Sun-3/Sun-2 graphics processor 
SYNOPSIS — SUN-3 

device gponeO at vme24dl6 ? csr 0x210000 priority 3 
SYNOPSIS — SUN-2 

device gponel at vme24 ? csr 0x210000 priority 3 
DESCRIPTION 

The gpone interface provides access to the optional Graphics Processor Board (GP). 

The hardware consumes 64 kilobytes of VME bus address space. The GP board starts at standard address 
0x210000 and must be configured for interrupt level 3. 

GPIOCTL 

The graphics processor responds to a number of ioctl calls as described here. One of the calls uses a 
gplfbinfo structure that looks like this: 
struct gplfbinfo { 


int 

fbvmeaddr; 

/* physical color board address */ 

int 

fbhwwidth; 

/* fb board width *1 

int 

fbhwheight; 

/* fb board height */ 

int 

addrdelta; 

/* phys addr diff between fb and gp */ 

caddrt 

fbiopaddr; 

/* cg2 va thru kemelmap */ 

int 

fbunit; 

/* fb unit to use for a,b,c,d */ 


}; 

The ioctl call looks like this: 

ioctl(flle, request, argp) 
int file, request; 

argp is defined differently for each GP ioctl request and is specified in the descriptions below. 

The following ioctl commands provide for transferring data between the graphics processor and color 
boards and processes. 

GP1IOPUTINFO 

Passes information about the frame buffer into driver, argp points to a struct gplfbinfo which is 
passed to the driver. 

GPlIO_GET_STATIC_BLOCK 

Hands out a static block from the GP. argp points to an int which is returned from the driver. 
GPlIO_FREE_STATIC_BLOCK 

Frees a static block from the GP. argp points to an int which is passed to the driver. 
GPlIO_GET_GBUFFER_STATE 

Checks to see if there is a buffer present on the GP. argp points to an int which is returned from 
the driver. 

GP1 IO_CHK_GP 

Restarts the GP if neccessary. argp points to an int which is passed to the driver. 

GP1 IO_GET_RESTART_COUNT 

Returns the number of restarts of a GP since power on. Needed to differentiate SIGXCPU calls in 
user processes, argp points to an int which is returned from the driver. 

GPlIO_REDIRECT_DEVFB 

Configures /devlfb to talk to a graphics processor device, argp points to an int which is passed to 
the driver. 

GPlIO_GET_REQDEV 

Returns the requested minor device, argp points to a dev_t which is returned from the driver. 
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GP1I0GETTRUMIN0RDEV 

Returns the true minor device, argp points to a char which is returned from the driver. 

The graphics processor driver also responds to the FBIOGTYPE, ioctl which a program can use to inquire as 
to the characteristics of the display device, the FBIOGINFO, ioctl for passing generic information, and the 
FBIOGPIXRECT ioctl so that SunWindows can run on it. See fbio( 4S). 

FILES 

/dev/gpone[0-3] [abed] 

/usr/include/sun/gpio.h 

/usr/include/pixrect/{gplcmds.h,gplreg.h,gplvar.h} 

SEE ALSO 

fbio(4S), mmap(2), gpconfig(8) 

Hardware Reference Manual for the Sun Graphics Processor (Sun 800-1190-01) 

Software Interface Manual for the Sun Graphics Processor 

DIAGNOSTICS 

The Graphics Processor has been restarted. You may see display garbage as a result. 
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ICMP(4P) 


NAME 

icmp - Internet Control Message Protocol 
SYNOPSIS 

None; included automatically with inet( 4F). 

DESCRIPTION 

The Internet Control Message Protocol, ICMP, is used by gateways and destination osts which process 
datagrams to communicate errors in datagram-processing to source hosts. The datagram level of Internet is 
discussed in ip( 4P). ICMP uses the basic support of IP as if it were a higher level protocol; however, 
ICMP is actually an integral part of IP. ICMP messages are sent in several situations; for example: when a 
datagram cannot reach its destination, when the gateway does not have the buffering capacity to forward a 
datagram, and when the gateway can direct the host to send traffic on a shorter route. 

The Internet protocol is not designed to be absolutely reliable. The purpose of these cr >trol messages is to 
provide feedback about problems in the communication environment, not to make IP eliable. There are 
still no guarantees that a datagram will be delivered or that a control message will >e returned. Some 
datagrams may still be undelivered without any report of their loss. The higher level protocols which use 
IP must implement their own reliability mechanisms if reliable communication is required. 

The ICMP messages typically report errors in the processing of datagrams; for fra^nented datagrams, 
ICMP messages are sent only about errors in handling fragment 0 of the datagram. ' o avoid the infinite 
regress of messages about messages etc., no ICMP messages are sent about ICMP messages. ICMP may 
however be sent in response to ICMP messages (for example, ECHOREPLY). There are eleven types of 
ICMP packets which can be received by the system. They are defined in this excerpt from 
<netinet/ip_icmp.h>, which also defines the values of some additional codes specifying he cause of certain 
errors. 


I* 

* Definition of type and code field values 

*/ 

#define ICMPECHOREPLY 
#define ICMPUNREACH 
#define ICMP UNREACH NET 
#define ICMPUNREACHHOST 
#define ICMP UNREACH PROTOCOL 
#define ICMP UNREACH PORT 
#define ICMP_UNREACH_NEEDFRAG 
#define ICMP UNREACH SRCFAIL 
#define ICMPSOURCEQUENCH 
#define ICMP_REDIRECT 
#define ICMP_REDIRECT_NET 
#define ICMP REDIRECT HOST 
#define ICMP_REDIRECT_TOSNET 
#define ICMPREDIRECTTOSHOST 
#define ICMPECHO 
#define ICMP_TIMXCEED 
#define ICMP_TIMXCEED_INTRANS 
#define ICMP TIMXCEED REASS 
#define ICMPPARAMPROB 
#define ICMPTSTAMP 
#define ICMP_TSTAMPREPLY 
#define ICMPIREQ 
#define ICMPIREQREPLY 


0 /* echo reply */ 

3 /* dest unreachable, codes */ 

0 I* bad net */ 

1 /* bad host */ 

2 I* bad protocol */ 

3 /* bad port */ 

4 I* IP DF caused drop */ 

5 /* src route failed */ 

4 I* packet lost, slow down -■/ 

5 /* shorter route, codes: */ 

0 /* for network */ 

1 /* for host */ 

2 /* for tos and net */ 

3 /* for tos and host */ 

8 /* echo service */ 

11 I* time exceeded, code: */ 

0 /* ttl==0 in transit */ 

1 /* ttl==0 in reass *1 

12 /* ip header bad */ 

13 /* timestamp request *1 

14 /* timestamp reply */ 

15 /* information request *1 

16 /* information reply */ 
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Arriving ECHO and TSTAMP packets cause the system to generate ECHOREPLY and TSTAMPREPLY 
packets. EREQ packets are not yet processed by the system, and are discarded. UNREACH, SOURCE- 
QUENCH, TIMXCEED and PARAMPROB packets are processed internally by the protocols implemented 
in the system, or reflected to the user if a raw socket is being used; see ip(4P). REDIRECT, ECHORE- 
PLY, TSTAMPREPLY and IREQREPLY are also reflected to users of raw sockets. In addition, 
REDIRECT messages cause the kernel routing tables to be updated; see routing(4N). 

SEE ALSO 

inet(4F), ip(4P) 

Internet Control Message Protocol, RFC792, J. Postel, USC-ISI (Sun 800-1064-01) 

BUGS 

IREQ messages are not processed properly: the address fields are not set 

Messages which are source routed are not sent back using inverted source routes, but rather go back 
through the normal routing mechanisms. 
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NAME 

ie - Intel 10 Mb/s Ethernet interface 
SYNOPSIS — SUN-3 

device ieO at obio ? csr OxcOOOO priority 3 

device iel at vme24dl6 ? csr 0x88000 priority 3 vector ieintr 117 

SYNOPSIS — SUN-2 

device ieO at virtual 2 csr 0xee3000 priority 3 
device ieO at mbmem ? csr 0x88000 priority 3 
device iel at mbmem ? csr 0x8c000 flags 2 priority 3 
device iel at vme24 ? csr 0x88000 priority 3 vector ieintr 117 

DESCRIPTION 

The ie interface provides access to a 10 Mb/s Ethernet network through a Intel controller chip. For a gen- 
eral description of network interfaces see i/(4N). 

In the synopsis — Sun-3 lines above, the first line specifies the first Intel Ethernet controller on a Sun- 
3/75M; the second line specifies the Intel Ethernet controller on other Sun-3 models. 

In the synopsis — Sun-2 lines above, the first line specifies the first Intel Ethernet controller on a Sun-2/ 120 
or Sun-2/170; the second line specifies the first Sun-2 Ethernet controller on a Sun-2/50 or Sun-2/160. 
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NAME 

if - general properties of network interfaces 


DESCRIPTION 

Each network interface in a system corresponds to a path through which messages may be sent and 
received. A network interface usually has a hardware device associated with it, though certain interfaces 
such as the loopback interface, lo(4), do not 


At boot time each interface which has underlying hardware support makes itself known to the system dur- 
ing the autoconfiguration process. Once the interface has acquired its address it is expected to install a 
routing table entry so that messages may be routed through it. Most interfaces require some part of then- 
address specified with an SIOCSIFADDR ioctl before they will allow traffic to flow through them. On 
interfaces where the network-link layer address mapping is static, only the network number is taken from 
the ioctl; the remainder is found in a hardware specific manner. On interfaces which provide dynamic 
network-link layer address mapping facilities (for example, lOMb/s Ethernets using arp (4P),), the entire 
address specified in the ioctl is used. 


The following ioctl calls may be used to manipulate network interfaces. Unless specified otherwise, the 
request takes an ifreq structure as its parameter. This structure has the form 
struct ifreq { 

char iff_name[16]; I* name of interface (e.g. "ecO") *1 

union { 


struct 
struct 
short 
} ifrifru; 
#define ifr addr 
#define ifr dstaddr 
#define ifr flags 
}; 


sockaddr ifruaddr; 
sockaddr ifrudstaddr; 
ifruflags; 

ifr_ifru.ifru_addr /* address */ 
iff_ifru.iffu_dstaddr /* other end of p-to-p link */ 

ifr_ifru.ifru_flags I* flags */ 


SIOCSIFADDR 

Set interface address. Following the address assignment, the “initialization” routine for the inter- 
face is called. 


SIOCGIFADDR 

Get interface address. 


SIOCSIFDSTADDR 

Set point to point address for interface. 

SIOCGIFDSTADDR 

Get point to point address for interface. 

SIOCSEFFLAGS 

Set interface flags field. If the interface is marked down, any processes currendy routing packets 
through the interface are notified. 

SIOCGIFFLAGS 

Get interface flags. 

SIOCGIFCONF 

Get interface configuration list. This request takes an ifconf structure (see below) as a value-result 
parameter. The ifcjen field should be initially set to the size of the buffer pointed to by ifc_buf. On 
return it will contain the length, in bytes, of the configuration list. 

/* 

* Structure used in SIOCGIFCONF request. 

* Used to retrieve interface configuration 

* for machine (useful for programs which 

* must know all networks accessible). 
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*/ 

struct ifconf { 

int ifc_len; /* size of associated buffer */ 

union { 

caddrt ifcu buf; 
struct ifreq *ifcu_req; 

} ifcifcu; 

#define ifc_buf ifc_ifcu.ifcu_buf /* buffer address */ 

#define ifc_req ifc_ifcu.ifcu_req /* array of structures returned */ 

}; 

SEE ALSO 

arp(4P), ec(4S), en(4S), lo(4) 
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NAME 

inet - Internet protocol family 

SYNOPSIS 

options INET 

DESCRIPTION 

The Internet protocol family is a collection of protocols layered atop the Internet Protocol (IP) transport 
layer, and using the Internet address format. The Internet family provides protocol support for the 
SOCKSTREAM, SOCK_DGRAM, and SOCKJR.AW socket types; the SOCK_RAW interface provides 
access to the DP protocol. 

ADDRESSING 

Internet addresses are four byte quantities, stored in network standard format (on the VAX these are word 
and byte reversed; on the Sun they are not reversed). The include file <netinet/in.h> defines the Internet 
address as a discriminated union. 

Sockets in the Internet protocol family use the following addressing structure: 
struct sockaddr in { 

short sin_family; 
u short sin_port; 
struct inaddr sinaddr; 
char sin_zero[8]; 

}; 

(Library routines to return and manipulate structures of this form are in section 3N of the manual; see 
mrro (3N) and the other section 3 entries mentioned under SEE ALSO below). Each socket has a local 
address which may be specified in this form, which can be established with bind( 2); the getsockname(2) 
call returns this address. Each socket also may be bound to a peer socket with an address specified in this 
form; this peer address can be specified in a connect (2) call, or transiently with a single message in a 
sendto or sendmsg call; see send (2). The peer address of a socket is returned by the getpeername (2) call. 

The sin_addr field of the socket address specifies the Internet address of the machine on which the socket is 
located. A special value may be specified or returned for this field, sin_addr.s_addr==INADDR_ANY. 
This address is a “wildcard” and matches any of the legal internet addresses on the local machine. This 
address is useful when a process neither knows (nor cares) what the local Internet address is, and even 
more useful for server processes which wish to service all requests of the current machine. Since a 
machine can have several addresses (one per hardware network interface), specifying a single address 
would restrict access to the service to those clients which specified the address of that interface. By speci- 
fying INADDR ANY, the server can arrange to service clients from all interfaces. 

When a socket address is bound, the networking system checks for an interface with the address specified 
on the current machine (unless, of course, a wildcard address is specified), and returns an error EAD- 
DRNOT AVAIL if no such interface is found. 

The local port address specified in a bind(2) call is restricted to be greater than IPPORTRESERVED 
(=1024, in <netinet/in.h>) unless the creating process is running as the super-user, providing a space of 
protected port numbers. The local port address is also required to not be in use in order for it to be 
assigned. This is checked by looking for another socket of the same type which has the same local address 
and local port number. If such a socket already exists, you will not be able to create another socket at the 
same address, and will instead get the error EADDRINUSE. If the local port address is specified as 0, then 
the system picks a unique port address not less than IPPORT RESERVED and assigns it to the port A 
unique local port address is also picked for a socket which is not bound but which is used with connect ( 2) 
or sendto (2); this allows tcp (4p) connections to be made by simply doing socket (2) and then connect (2) in 
the case where the local port address is not significant; it is defaulted by the system. Similarly if you are 
sending datagrams with udp( 4P) and do not care which port they come from, you can just do socket (2) and 
sendto (2) and let the system pick a port number. 
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Let us say that two sockets are incompatible if they have the same port number, are not conected to other 
sockets, and do not have different local host addresses. (It is possible to have two sockets with the same 
port number and different local host addresses because a machine may have several local addresses from 
its different network interfaces.) The Internet system does not allow such incompatible sockets to exist on 
a single machine. Consider a socket which has a specific local host and local port number on the current 
machine. If another process tries to create a socket with a wildcard local host address and the same port 
number then that request will be denied. For connection based sockets this prevents these two sockets from 
attempting to connect to the same foreign host/socket, and thereby causing great havoc. For connectionless 
sockets this prevents the dilemma which would result from trying to determine who to deliver an incoming 
datagram to (since more than one socket could match an address given on a datagram). The same restric- 
tion applies if the wildcard socket exists first (If both sockets are wildcard, then the normal restrictions on 
duplicate addresses apply.) 

A socket option SOREUSEADDR exists to allow incompatible sockets to be created. This option is 
needed to implement the File Transfer Protocol (FTP) which requires that a connection be made from an 
existing port number (the port number of its primary connection) to a different port number on the same 
remote host The danger here is that the user would attempt to connect this second port to the same remote 
host/port that the primary connection was using. In using SO REUSEADDR the user is pledging not to do 
this, since this will cause the first connection to abort. 

When a connect ( 2) is done, the Internet system first checks that the socket is not already connected. If 
does not allow connections to port number 0 on another host, nor does it allow connections to a wildcard 
host (sin_addr.s_addr==INADDR_ANY); attempts to do this yield EADDRINUSE. If the socket from 
which the connection is being made currently has a wildcard local address (either because it was bound to a 
specific port with a wildcard address, or was never subjected to bind( 2)), then the system picks a local 
Internet address for the socket from the set of addresses of interfaces on the local machine. If there is an 
interface on the local machine on the same network as the machine being connected to, then that address is 
used. Otherwise, the “first” local network interface is used (this is the one that prints out first in “netstat 
-i”; see netstat ( 8)). Although it is not supposed to matter which interface address is used, in practice it 
would probably be better to select the address of the interface through which the packets are to be routed. 
This is not currently done (as it would involve a fair amount of additional overhead for datagram transmis- 
sion). 

PROTOCOLS 

The Internet protocol family supported by the operating system is comprised of the Internet Datagram Pro- 
tocol (IP) ip(4P), Address Resolution Protocol (ARP) arp( 4P), Internet Control Message Protocol (ICMP) 
icmp(4P), Transmission Control Protocol (TCP) fcp(4P), and User Datagram Protocol (UDP) udp (4P). 

TCP is used to support the SOCK STREAM abstraction while UDP is used to support the 
SOCK_DGRAM abstraction. A raw interface to IP is available by creating an Internet socket of type 
SOCK_RAW; see ip (4 P). The ICMP message protocol is most often used by the kernel to handle and 
report errors in protocol processing; it is, however, accessible to user programs. The ARP protocol is used 
to translate 32-bit Internet host numbers into the 48-bit addresses needed for an Ethernet. 

SEE ALSO 

intro(3N), byteorder(3N), gethostent(3N), getnetent(3N), getprotoent(3N), getservent(3N), inet(3N), 
network(3N), arp(4P), tcp(4P), udp(4P), ip(4P) 

Internet Protocol Transition Workbook, Network Information Center, SRI (Sun 800-1056-01) 

Internet Protocol Implementation Guide, Network Information Center, SRI (Sun 800-1055-01) 

A 4.2BSD Interprocess Communication Primer 
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NAME 

ip - Internet Protocol 
SYNOPSIS 

None; included by default with inet( 4F). 

DESCRIPTION 

The Internet Protocol is designed for use in interconnected systems of packet-switched computer communi- 
cation networks. It provides for transmitting blocks of data called “datagrams” from sources to destina- 
tions, where sources and destinations are hosts identified by fixed-length addresses. It also provides for 
fragmentation and reassembly of long datagrams, if necessary, for transmission through “small packet” 
networks. 

IP is specifically limited in scope. There are no mechanisms to augment end-to-end data reliability, flow 
control, sequencing, or other services commonly found in host-to-host protocols. IP can capitalize on the 
services of its supporting networks to provide various types and qualities of service. 

IP is called on by host-to-host protocols, including tcp (4P) a reliable stream protocol, udp( 4P) a socket- 
socket datagram protocol, and nd(4 P) the network disk protocol. Other protocols may be layered on top of 
IP using the raw protocol facilities described here to receive and send datagrams with a specific IP protocol 
number. The IP protocol calls on local network drivers to carry the internet datagram to the next gateway 
or destination host. 

When a datagram arrives at a UNIX system host, the system performs a checksum on the header of the 
datagram. If this fails, or if the datagram is unreasonably short or the header length specified in the 
datagram is not within range, then the datagram is dropped. Checksumming of Internet datagrams may be 
disabled for debugging purposes by patching the kernel variable ipcksum to have the value 0. 

Next the system scans the IP options of the datagram. Options allowing for source routing (see 
routing (4N)) and also the collection of time stamps as a packet follows a particular route (for network 
monitoring and statistics gathering purposes) are handled; other options are ignored. Processing of source 
routing options may result in an UNREACH icmp{ 4P) message because the source routed host is not acces- 
sible. 

After processing the options, IP checks to see if the current machine is the destination for the datagram. If 
not, then IP attempts to forward the datagram to the proper host Before forwarding the datagram, IP decre- 
ments the time to live field of the datagram by IPTTLDEC seconds (currently 5 from <netinet/ip.h>), and 
discards the datagram if its lifetime has expired, sending an ICMP TIMXCEED error packet back to the 
source host. Similarly if the attempt to forward the datagram fails, then ICMP messages indicating an 
unreachable network, datagram too large, unreachable port (datagram would have required broadcasting on 
the target interface, and IP does not allow directed broadcasts), lack of buffer space (reflected as a source 
quench), or unreachable host. Note however, in accordance with the ICMP protocol specification, ICMP 
messages are returned only for the first fragment of fragmented datagrams. 

It is possible to disable the forwarding of datagrams by a host by patching the kernel variable ipforwarding 
to have value 0. 

If a packet arrives and is destined for this machine, then IP must check to see if other fragments of the same 
datagram are being held. If this datagram is complete, then any previous fragments of it are discarded. If 
this is only a fragment of a datagram, it may yield a complete set of pieces for the datagram, in which case 
IP constructs the complete datagram and continues processing with that. If there is yet no complete set of 
pieces for this datagram, then all data thus far received is held (but only one copy of each data byte from 
the datagram) in hopes that the rest of the pieces of the fragmented datagram will arrive and we will be 
able to proceed. We allow IPFRAGTTL (currently 15 in <netinet/ip.h>) seconds for all the fragments of a 
datagram to arrive, and discard partial fragments then if the datagram has not yet been completely assem- 
bled. 

When we have a complete input datagram it is passed out to the appropriate protocol’s input routine: either 
tcp( 4P), udp( 4P), nd( 4P), icmp (4P) or a user process through a raw IP socket as described below. 
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Datagrams are output by the system-implemented protocols fcp(4P), udp( 4P), nd( 4P), and icmp{ 4P); as 
well as by packet forwarding operations and user processes through raw IP sockets. Output packets are 
normally subjected to routing as described in routing(4iii). However, special processes such as the routing 
daemon routed( 8C) occasionally use the SODONTROUTE socket option to make packets avoid the routing 
tables and go direcdy to the network interface with the network number which the packet is addressed to. 
This may be used to test the ability of the hardware to transmit and receive packets even when we believe 
that the hardware is broken and have therefore deleted it from the routing tables. 

If there is no route to a destination address or if the SO DONTROUTE option is given and there is no inter- 
face on the network specified by the destination address, then the IP output routine returns a ENETUN- 
REACH error. (This and the other IP output errors are reflected back to user processes through the various 
protocols, which individually describe how errors are reported.) 

In the (hopefully normal) case where there is a suitable route or network interface, the destination address 
is checked to see if it specifies a broadcast (address INADDRANY; see inet(4F)); if it does, and the 
hardware interface does not support broadcasts, then an EADDRNOT AVAIL is returned; if the caller is not 
the super-user then a EACCESS error will be returned. IP also does not allow broadcast messages to be frag- 
mented, returning a EMSGSIZE error in this case. 

If the datagram passes all these tests, and is small enough to be sent in one chunk, then the system calls the 
output routine for the particular hardware interface to transmit the packet. The interface may give an error 
indication, which is reflected to IP output’s caller; see the documentation for the specific interface for a 
description of errors it may encounter. If a datagram is to be fragmented, it may have the IP DF (don’t 
fragment) flag set (although currently this can happen only for forwarded datagrams). If it does, then the 
datagram will be rejected (and result in an ICMP error datagram). If the system runs out of buffer space in 
fragmenting a datagram then a ENOBUFS error will be returned. 

IP provides a space of 255 protocols. The known protocols are defined in <netinet/in.h>. The ICMP, TCP, 
UDP and ND protocols are processed internally by the system; others may be accessed through a raw socket 
by doing: 

s = socket(AF_INET, SOCK_RAW, IPPROTO_xxx); 

Datagrams sent from this socket will have the current host’s address and the specified protocol number; the 
raw IP driver will construct an appropriate header. When IP datagrams are received for this protocol they 
are queued on the raw socket where they may be read with recvfrom; the source IP address is reflected in 
the received address. 

SEE ALSO 

send(2), recv(2), inet(4F) 

Internet Protocol, RFC791, USC-ISI (Sun 800-1063-01) 

BUGS 

One should be able to send and receive IP options. 

Raw sockets should receive ICMP error packets relating to the protocol; currently such packets are simply 
discarded. 
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NAME 

ip - Disk driver for Interphase 2180 SMD Disk Controller 
SYNOPSIS — SUN-2 

controller ipcO at mbio ? csr 0x040 priority 2 

controller ipcl at mbio ? csr 0x044 priority 2 

disk ipO at ipcO driveO 

disk ipl at ipcO drivel 

disk ip2 at ipcl driveO 

disk ip3 at ipcl drivel 

DESCRIPTION 

Special files ip* refer to disk devices controlled by an Interphase SMD 2180 disk controller. 

The standard ip device names begin with the letters “ip”, followed by the drive unit number, followed by a 
letter from the series a - h to name one of the eight partitions on the drive. For example, Idevliplc refers to 
partition c on the second drive controlled by the Interphase controller. 

The device names provide the binding into the minor device numbers for the driver software. Files with 
minor device numbers 0 through 7 refer to the eight partitions (a - h) of unit 0; files with device numbers 8 
through 15 refer to the eight partitions of drive 1, and so on. 

The block files access the disk via the system’s normal buffering mechanism, and may be read and written 
without regard to physical disk records. There is also a ‘raw’ interface which provides for direct transmis- 
sion between the disk and the user’s read or write buffer. A single read or write call results in exactly one 
I/O operation and therefore raw I/O is considerably more effficient when many words are transmitted. 
Raw files conventionally have a leading “r” — IdevIripOc, for instance. 

In raw I/O, counts should be a multiple of 512 bytes (a disk sector). Likewise seek calls should specify a 
multiple of 512 bytes. 

DISK SUPPORT 

This driver handles all SMD drives by reading a label from sector 0 of the drive which describes the disk 
geometry and partitioning. 

The ip?a partition is normally used for the root file system on a disk, the ip?b partition as a paging area, and 
the ip?c partition for pack-pack copying (it normally maps the entire disk). The rest of the disk is normally 
the ip?g partition. 

FILES 

/dev/ip[0-7][a-h] block files 
/dev/rip[0-7][a-h]raw files 

SEE ALSO 

dkio(4S), xy(4S) 

“Interphase SMD2180 Storage Module Controller/Formatter - User’s Guide’ ’ (Sun 800-0274) 
DIAGNOSTICS 

ip%d: SMD-2180. When booting tells the controller type. 

ip%d: initialization failed. Because the controller didn’t respond; perhaps another device is at the address 
the system expected an Interphase controller at. 

ip%d: error %\ reading label on head %d. Error reading drive geometry/partition table information. 
ip%d: Corrupt label on head %d. The geometry/partition label checksum was incorrect 

ip%d: Misplaced label on head %d. A disk label was copied to the wrong head on the disk; shoudn’t 
happen. 

ip%d: Unsupported phys partition # %d. This indicates a bad label. 
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ip%d: unit not online. 

ip%d%c: cmd how (msg) blk %d. A command such as read, write, or format encountered a error condi- 
tion (how): either it failed, the unit was restored, or an operation was retry’ ed. The msg is derived from the 
error number given by the controller, indicating a condition such as “drive not ready”, “sector not found” 
or 4 ‘disk write protected’ ’ . 

BUGS 

In raw I/O read and write ( 2) truncate file offsets to 512-byte block boundaries, and write scribbles on the 
tail of incomplete blocks. Thus, in programs that are likely to access raw devices, read, write and lseek( 2) 
should always deal in 512-byte multiples. 
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NAME 

kb - Sun keyboard 
SYNOPSIS 

pseudo-device kb number 
DESCRIPTION 

Kb provides access to the Sun workstation keyboard translation. Definitions for altering keyboard transla- 
tion are in <sundev/kbio.h> and <sundev/kbd.h>. The number argument specifies the maximum number of 
keyboards supported by the system. 

Keyboard Translation State: 

The call KIOCTRANS controls the presence of keyboard translation: 

#define TRNONE 0 

#define TRASCII 1 

#define TR EVENT 2 


intx; 

err = ioctl(fd, KIOCTRANS, &x); 

When x is TR NONE, keyboard translation is turned off and up/down key codes are reported. Specifying 
x as TR ASCII causes ASCII to be reported. Specifying x as TR EVENT causes Firmevents to be 
reported (see below). 

The call KIOCGTRANS determines the current state of keyboard translation. 


intx; 

err = ioctl(fd, KIOCGTRANS, &x); 

Keyboard Translation Table Entries: 

The call KIOCSETKEY changes a keyboard translation table entry: 


struct kiockey { 

int kiotablemask; 

#define KIOCABORT1 -1 
#define KIOCABORT2 -2 
uchar kio_station; 
uchar kio entry; 
char kio_string[10]; 

}; 


/* Translation table (one of: 0, CAPSMASK, 
SHIFTMASK, CTRLMASK, UPMASK) */ 

I* Special "mask": abortl keystation */ 

/* Special "mask": abort2 keystation */ 

/* Physical keyboard key station (0-127) *1 
/* Translation table station’s entry */ 

/* Value for STRING entries (null terminated) */ 


struct kiockey key; 

err = ioctl(fd, KIOCSETKEY, &key); 

Set kio tablemask table’s Hostation to kio_entry. Copy kio_string to string table if kio entry is between 
STRING and STRING+15. This call may return EINVAL if there are invalid arguments. 

There are a couple special values of kiojablemask that affect the two step “break to the prom monitor” 
sequence. The usual sequence is <Setup>a. If kiojablemask is KIOCABORT1 then the value of 
kio_station is set to be the first keystation in the sequence. If kiojablemask is KIOCABORT2 then the 
value of kio_station is set to be the second keystation in the sequence. 

The call KIOCGETKEY determines the current value of a keyboard translation table entry: 
struct kiockey key; 

err = ioctl(fd, KIOCGETKEY, &key); 
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Get Hojablema.sk table’s Ho station to kio_entry. Get Ho_string from string table if kio_entry is between 
STRING and STRING+15. This call may return EINVAL if there are invalid arguments. 

Keyboard Type: 

TBD The call KIOCTYPE returns the type of the keyboard: 


#define KB KLUNK 

0x00 

/* Micro Switch 103SD32-2 */ 

#define KB VT100 

0x01 

I* Keytronics VT100 compatible */ 

#define KB SUN2 

0x02 

/* Sun-2 custom keyboard */ 

#define KB SUN3 

0x03 

/* Sun-3 custom keyboard */ 

#define KB ASCII 

OxOF 

/* Ascii terminal masquerading as kbd */ 

intx; 



err = ioctl(fd, KIOCTYPE, &x); 



When x is -1, the keyboard type is unknown. 

Keyboard Commands: 

The call KIOCCMD sends a command to the keyboard: 

/* 

* Commands to the Sun-2 keyboard. 

*1 

#define KBD CMD RESET 0x01 

#define KBDCMDBELL 0x02 

#define KBDCMDNOBELL 0x03 

/* 

* Commands to the Sun-3 keyboard. KBD CMD BELL & KBD CMD NOBELL work 

* as well. 

*1 

#define KBD CMD CLICK OxOA /* Turn on the click annunciator */ 

#define KBD CMD NOCLICKOxOB /* Turn off the click annunciator *1 

intx; 

err = ioctl(fd, KIOCCMD, &x); 

Inappropriate commands for particular keyboard types are ignored. Since there is no reliable way to get 
the state of the bell or click (because we can’t query the kdb, and also one could do writes to the appropri- 
ate serial driver— thus going around this ioctl) we don’t provide an equivalent state querying ioctl. 

FILES 

/dev/kbd 

SEE ALSO 

kbd(5), click(l) 

The SunView System Programmer’ s Guide - Appendix: Writing a Virtual User Input Device Driver 
(describes Firm_event format) 


/* Reset keyboard as if power-up *1 
/* Turn on the bell */ 

/* Turn off the bell */ 
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NAME 

le - Sun-3/50 10 Mb/s Ethernet interface 
SYNOPSIS 

device leO at obio ? csr 0x120000 priority 3 
DESCRIPTION 

The le interface provides access to a 10 Mb/s Ethernet network through a Sun-3 controller using the AMD 
LANCE (Local Area Network Controller for Ethernet) Am7990 chip. For a general description of network 
interfaces see i/(4N). 

The synopsis line above specifies the first and only Ethernet controller on a Sun-3/50. 

DIAGNOSTICS 

le%d: transmitter frozen -- resetting A bug in the LANCE chip has caused the chip’s transmitter section 
to stop. The driver has detected this condition and reinitialized the chip. 

le%d: out of mbufs: output packet dropped The driver has run out of memory to use to buffer packets 
on output The packet being transmitted at the time of occurrence is lost This error is usually symp- 
tomatic of trouble elsewhere in the kernel. 

le%d: stray transmitter interrupt The LANCE chip has signalled that it completed transmitting a packet 
but the driver has sent no such packet. 

le%d: LANCE Rev C/D Extra Byte(s) bug; Packet dropped The LANCE chip’s internal silo pointers 
have become misaligned. This error arises from a chip bug. 

le%d: trailer error An incoming packet claimed to have a trailing header but did not. 

le%d: runt packet An incoming packet’s size was below the Ethernet minimum transmission size. 

le%d: Receive buffer error - BUFF bit set in rmd This error “should never happen,” as it occurs only 
in conjunction with a LANCE feature that the driver does not use. 

le%d: Received packet with STP bit in rmd cleared This error “should never happen,” as it occurs 
only in conjunction with a LANCE feature that the driver does not use. 

Ie%d: Received packet with ENP bit in rmd cleared This error “should never happen,” as it occurs 
only in conjunction with a LANCE feature that the driver does not use. 

Ie%d: Transmit buffer error - BUFF bit set in tmd Excessive bus contention has prevented the LANCE 
chip from gathering packet contents quickly enough to sustain the packet’s transmission over the Ethernet 
The affected packet is lost. 

le%d: Transmit late collision - Net problem? A packet collision has occurred after the channel’s slot 
time has elapsed. This error usually indicates faulty hardware elsewhere on the net. 

le%d: No carrier - transceiver cable problem? The LANCE chip has lost input to its carrier detect pin 
while trying to transmit a packet. 

Ie%d: Transmit retried more than 16 times - net jammed Network activity has become so intense that 
sixteen successive transmission attempts failed, causing the LANCE chip to give up on the current packet. 

le%d: missed packet The driver has dropped an incoming packet because it had no buffer space for it. 

le%d: Babble error - sent a packet longer than the maximum length While transmitting a packet, the 
LANCE chip has noticed that the packet’s length exceeds the maximum allowed for Ethernet. This error 
indicates a kernel bug. 

le%d: Memory Error! Ethernet chip memory access timed out The LANCE chip timed out while try- 
ing to acquire the bus for a DVMA transfer. 

le%d: Reception stopped Because of some other error, the receive section of the LANCE chip shut down 
and had to be restarted. 
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Ie%d: Transmission stopped Because of some other error, the transmit section of the LANCE chip shut 
down and had to be restarted. 
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NAME 

lo - software loopback network interface 

SYNOPSIS 

pseudo-device loop 

DESCRIPTION 

The loop device is a software loopback network interface; see i/(4N) for a general description of network 
interfaces. 

The loop interface is used for performance analysis and software testing, and to provide guaranteed access 
to Internet protocols on machines with no local network interfaces. A typical application is the comsat (8C) 
server which accepts notification of mail delivery through a particular port on the loopback interface. 

By default, the loopback interface is accessible at Internet address 127.0.0.1 (non-standard); this address 
may be changed with the SIOCSIFADDR ioctl. 

DIAGNOSTICS 

Io%d: can’t handle af%d. The interface was handed a message with addresses formatted in an unsuitable 
address family; the packet was dropped. 

SEE ALSO 

if(4N), inet(4F) 

BUGS 

It should handle all address and protocol families. An approved network address should be reserved for 
this interface. 
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NAME 

mem, kmem, vmel6dl6, vme24dl6, vme32dl6, vmel6d32, vme24d32, vme32d32, mbmem, mbio, - main 
memory and bus I/O space 

SYNOPSIS 

None; included with standard system. 

DESCRIPTION 

These devices are special files that map memory and bus I/O space. They may be read, written, seek’ed 
and (except for kmem) mmap( 2)’ed. 

Mem is a special file that is an image of the physical memory of the computer. It may be used, for exam- 
ple, to examine (and even to patch) the system. 

Kmem is a special file that is an image of the kernel virtual memory of the system. 

vmel6dl6 (also known as vmel6) is a special file that is an image of VMEbus 16-bit addresses with 16-bit 
data. Vmel6 address space extends from 0 to 64K. 

vme24d!6 (also known as vme24) is a special file that is an image of VMEbus 24-bit addresses with 16-bit 
data. Vme24 address space extends from 0 to 16 Megabytes. The VME 16-bit address space overlaps the 
top 64K of the 24-bit address space. 

SUN-3 VMEBUS ONLY 

vme32dl6 is a special file that is an image of VMEbus 32-bit addresses with 16-bit data. 

vmel6d32 is a special file that is an image of VMEbus 16-bit addresses with 32-bit data. 

vme24d32 is a special file that is an image of VMEbus 24-bit addresses with 32-bit data. 

vme32d32 (also known as vme32 ) is a special file that is an image of VMEbus 32-bit addresses with 32-bit 
data. Vme32 address space extends from 0 to 4 Gigabytes. The VME 24-bit address space overlaps the 
top 16 Megabytes of the 32-bit address space. 

vme* type special files can only be accessed in VME based systems. 

SUN-2 MULTIBUS ONLY 

Mbmem is a special file that is an image of the Multibus memory of the system. Multibus memory is in the 
range from 0 to 1 Megabyte. Mbmem can only be accessed in Multibus based systems. 

Mbio is a special file that is an image of the Multibus I/O space. Multibus I/O space extends from 0 to 
64K. Mbio can only be accessed in Multibus based systems. 

When reading and writing mbmem and mbio odd counts or offsets cause byte accesses and even counts and 
offsets cause word accesses. 

FILES 

/dev/mem 

/dev/kmem 

/dev/mbmem 

/dev/mbio 

/dev/vmel6dl6 

/dev/vmel6 

/dev/vme24dl6 

/dev/vme24 

/dev/vme32dl6 

/dev/vmel6d32 

/dev/vme24d32 

/dev/vme32d32 

/dev/vme32 
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NAME 

mouse - Sun mouse 

SYNOPSIS 

pseudo-device ms3 

DESCRIPTION 

The mouse interface provides access to the Sun Workstation mouse. 

The mouse incorporates a microprocessor which generates a byte-stream protocol encoding mouse 
motions. 

Each mouse sample in the byte stream consists of three bytes: the first byte gives the button state with 
value 0x87| 'but, where but is the low three bits giving the mouse buttons, where a 0 (zero) bit means that a 
button is pressed, and a 1 (one) bit means a button is not pressed. Thus if the left button is down the value 
of this sample is 0x83, while if the right button is down the byte is 0x86. 

The next two bytes of each sample give the x and y delta’s of this sample as signed bytes. The mouse uses 
a lower-left coordinate system, so moves to the right on the screen yield positive x values and moves down 
the screen yield negative y values. 

The beginning of a sample is identifiable because the delta’s are constrained to not have values in the range 
0x80-0x87. 

The mouse can be used as a device that emits Firmevents as specified by the protocol of a Virtual User 
Input Device. It understands VUIDSFORMAT, VUIDGFORMAT, VUIDSADDR and VUIDGADDR 
ioctls (see reference below). 

FILES 

/dev/mouse 

SEE ALSO 

win(4S) 

The SunView System Programmer’ s Guide 
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NAME 

mti - Systech MTI-800/1600 multi-terminal interface 
SYNOPSIS — SUN-3 

device mtiO at vmel6dl6 ? csr 0x620 flags Oxffff priority 4 vector mtiintr 136 
SYNOPSIS — SUN-2 

device mtiO at mbio ? csr 0x620 flags Oxffff priority 4 

device mtiO at vmel6 ? csr 0x620 flags Oxffff priority 4 vector mtiintr 136 

DESCRIPTION 

The Systech MTI card provides 8 (MTI-800) or 16 (MTI-1600) serial communication lines with modem 
control. Each line behaves as described in tty( 4). Input and output for each line may independently be set 
to run at any of 16 speeds; see tty (4) for the encoding. 

Bit i of flags may be specified to say that a line is not properly connected, and that the line i should be 
treated as hard-wired with carrier always present Thus specifying “flags 0x0004” in the specification of 
mtiO would cause line tty02 to be treated in this way. 

To allow a single tty line to be connected to a modem and used for both incoming and outgoing calls, a 
special feature, controlled by the minor device number, has been added. Minor device numbers in the 
range 0 - 127 correspond directly to the normal tty lines and are named tty*. Minor device numbers in the 
range 128 - 256 correspond to the same physical lines as those above (i.e. the same line as the minor dev- 
ice number minus 128) and are (conventionally) named cua*. The cua lines are special in that they can be 
opened even when there is no carrier on the line. Once a cua line is opened, the corresponding tty line can 
not be opened until the cua line is closed. Also, if the tty line has been opened successfully (usually only 
when carrier is recognized on the modem) the corresponding cua line can not be opened. This allows a 
modem to be attached to Idev/ttyOO (usually renamed to Idev/ttydO) and used for dialin (by enabling the line 
for login in /etclttys) and also used for dialout (by tip( 1C) or uucp(\C)) as Idev/cuaO when no one is logged 
in on the line. Note that the bit in the flags word in the config file (see above) must be zero for this line. 

WIRING 

The Systech requires the CTS modem control signal to operate. If the device does not supply CTS then 
RTS should be jumpered to CTS at the distribution panel (short pins 4 to 5). Also, the CD (carrier detect) 
line does not work properly. When connecting a modem, the modem’s CD line should be wired to DSR, 
which the software will treat as carrier detect. 

FILES 

/dev/tty0[0-9a-f] hardwired tty lines 
/dev/ttyd[0-9a-f] dialin tty lines 
/dev/cua[0-9a-f] dialout tty lines 

SEE ALSO 

tty(4), zs(4S) 

The MTI-800AI1600A Multiple Terminal Interface User’ s Manual, Rev. D, which comes with the multi- 
plexer. 

DIAGNOSTICS 

Most of these diagnostics “should never happen” and their occurrence usually indicates problems else- 
where in the system. 

mti%d,%d: silo overflow. More than 512 characters have been received by the mti hardware without 
being read by the software. Extremely unlikely to occur. 

mti%d: error %x. The mti returned the indicated error code. See the mti manual. 

mti%d: DMA output error. The mti encountered an error while trying to do DMA output. 

mti%d: impossible response %x. The mti returned an error it couldn’t understand. 
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NAME 

mtio - UNIX system magnetic tape interface 
SYNOPSIS 

#include <sys/ioctI.h> 

#include <sys/mtio.h> 

DESCRIPTION 

The files mtO, .... mtl5 refer to the UNIX system magnetic tape drives, which read and write magnetic tape 
in 2048 byte blocks (the 2048 is actually BLKDEV IOSIZE in <sys/param.h>). The following description 

applies to any of the transport/controller pairs. The files mtO , .... mt3 and mt8 mill are rewound when 

closed; the others are not. When a nine track tape file, open for writing or just written, is closed, two end- 
of-files are written; if the tape is not to be rewound it is positioned with the head between the two tape- 
marks. When a 1/4" tape file, (due to a bug, only if) just written, is closed, only one end of file mark is 
written because of the inability to overwrite data on a 1/4" tape; see below. 

1/4" tapes are not able to back up and always write fixed sized blocks. Since they cannot back up, they 
cannot support backward space file and backward space record. Since they always write fixed sized 
blocks, the size of transfers using the raw interface (see below) must be a multiple of the underlying block- 
size, usually 512 bytes. 

1/4" tapes also have an unusual tape format. They have parallel tracks, but only record information on one 
track at a time, switching to another track near the physical end of the medium. They erase all the tracks at 
once while writing the first track. Therefore, they cannot, in general, overwrite previously written data. If 
the old data were not on the first track, it would not be erased before being overwritten, and the result 
would be unreadable. 

The mt files discussed above are useful when it you want to access the tape in a way compatible with ordi- 
nary files. When using foreign tapes, and especially when reading or writing long records, the ‘raw’ inter- 
face is appropriate. The associated files are named rmtO , .... rmtlS, but the same minor-device considera- 
tions as for the regular files still apply. Each read or write call reads or writes the next record on the tape. 
In the write case the record has the same length as the buffer given. During a read, the record size is 
passed back as the number of bytes read, provided it is no greater than the buffer size. In raw tape I/O 
seeks are ignored. A zero byte count is returned when a tape mark is read, but another read will fetch the 
first record of the new tape file. 

A number of additional ioctl operations are available on raw magnetic tape. The following definitions are 
from <sys/mtio.h>: 

/* 

* Structures and definitions for mag tape I/O control commands 
*/ 


I* structure for MTIOCTOP - mag tape op command */ 


struct 

mtop { 
short mt_op; 


1* operations defined below */ 

}; 

daddr_t mt count; 

/* how many of them */ 

/* operations */ 



#define 

MTWEOF 

0 

/* write an end-of-file record */ 

fdefine 

MTFSF 1 


/* forward space file */ 

#define 

MTBSF2 


/* backward space file */ 

#define 

MTFSR3 


/* forward space record */ 

fdefine 

MTBSR4 


I* backward space record */ 

fdefine 

MTREW 

5 

1* rewind */ 

fdefine 

MTOFFL 

6 

1* rewind and put the drive offline *1 

fdefine 

MTNOP 

7 

/* no operation, sets status only *1 
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#define MTRETEN 8 /* retension the tape */ 

#define MTERASE 9 /* erase the entire tape *1 

/* structure for MTIOCGET - mag tape get status command */ 

struct mtget { 

short mttype; /* type of magtape device */ 

/* the following two registers are grossly device dependent */ 
short mt_dsreg; /* “drive status” register */ 

short mt_erreg; /* “error” register */ 

/* end device-dependent registers */ 

short mt resid; /* residual count */ 

/* the following two are not yet implemented */ 
daddrt mt_fileno; /* file number of current position */ 

daddrt mt_blkno; /* block number of current position */ 

I* end not yet implemented */ 

}; 

/* 

* Constants for mt type byte 
*/ 


#define MT ISTS 

0x01 

/* vax: unibus ts-11 */ 

#define MT ISHT 

0x02 

/* vax: massbus tu77, etc */ 

#define MT ISTM 

0x03 

1* vax: unibus tm-11 */ 

#define MT ISMT 

0x04 

/* vax: massbus tu78 *1 

#define MT ISUT 

0x05 

1* vax: unibus gcr */ 

#define MT ISCPC 

0x06 

1* sun: Multibus tapemaster */ 

#define MT ISAR 

0x07 

/* sun: Multibus archive */ 

#define MT ISSC 

0x08 

1* sun: SCSI archive */ 

#define MT ISXY 

0x09 

/* sun: Xylogics 472 */ 


/* mag tape io control commands *1 

#define MTIOCTOP _IOW(m, 1, struct mtop) /* do a mag tape op */ 

#define MTIOCGET _IOR(m, 2, struct mtget) /* get tape status */ 

#ifndef KERNEL 

#define DEFTAPE 7dev/rmtl2" 

#endif 

FILES 

/dev/mt* 

/dev/rmt* 

/dev/rar* 

SEE ALSO 

mt(l), tar(l), ar(4s), tm(4s), st(4s), xt(4s) 
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NAME 

nd - network disk driver 

SYNOPSIS 

pseudo-device nd 

DESCRIPTION 

The network disk device, Idev/nd*, allows a client workstation to perform disk I/O operations on a server 
system over the network. To the client system, this device looks like any normal disk driver: it allows 
read/write operations at a given block number and byte count. Note that this provides a network disk block 
access service rather than a network file access service. 

Typically the client system will have no disks at all. In this case Idev/ndO contains the client’s root file sys- 
tem (including /usr files), and ndl is used as a paging area. Client access to these devices is converted to 
net disk protocol requests and sent to the server system over the network. The server receives the request, 
performs the actual disk I/O, and sends a response back to the client. 

The server contains a table which lists the net address of each of his clients and the server disk partition 
which corresponds to each client unit number (ndO,l,.„). This table resides in the server kernel in a struc- 
ture owned by the nd device. The table is initialized by running the program letclnd with text file 
letc/nd.local as its input letclnd then issues ioctl(2) functions to load the table into the kernel. 

In addition to the read/write units Idevlnd*, there are public read-only units which are named Idev/ndp*. 
The correspondence to server partitions is specified by the letc/nddocal text file, in a similar manner to the 
private partitions. The public units can be used to provide shared access to binaries or libraries (/bin, 
lusr/bin, lusrlucb, lusr/lib) so that each diskless client does not have to consume space in his private parti- 
tions for these files. This is done by providing a public file system at the server ( Idev/ndpO ) which is 
mounted on /pub of each diskless client. The clients then use symbolic links to read the public files: /bin -> 
/pub /bin, lusrlucb -> Ipublusrlucb. One requirement in this case is that the server (who has read/write 
access to this file system) should not perform write activity with any public filesystem. This is because 
each client is locally cacheing blocks, and may get out of sync with the physical disk image. In certain 
cases, the client will detect an inconsistency and panic. 

One last type of unit is provided for use by the server. These are called local units and are named 
Idevlndl*. The Sun physical disk sector 0 label only provides a limited number of partitions per physical 
disk (eight). Since this number is small and these partitions have somewhat fixed meanings, the nd driver 
itself has a subpartitioning capability built-in. This allows the large server physical disk partition (e.g. 
IdevIxyOg ) to be broken up into any number of diskless client partitions. Of course on the client side these 
would be referenced as Idev/ndO,!,... ; but the server needs to reference these client partitions from time to 
time, to do mkfs( 8) and/jck(8) for example. The Idevlndl* entries allow the server ‘local’ access to his 
subpartitions without causing any net activity. The actual local unit number to client unit number 
correspondence is again recorded in the letclnd.local text file. 

The nd device driver is the same on both the client and server sides. There are no user level processes 
associated with either side, thus the latency and transfer rates are close to maximal. 

The minor device and ioctl encoding used is given in file <sun/ndio.h>. The low six bits of the minor 
number are the unit number. The 0x40 bit indicates a public unit; the 0x80 bit indicates a local unit. 

INITIALIZATION 

No special initialization is required on the client side; he finds the server by broadcasting the initial 
request Upon getting a response, he locks onto that server address. 

At the server, the nd( 8c) command initializes the network disk service by issuing ioctl’s to the kernel. 
ERRORS 

Generally physical disk I/O errors detected at the server are returned to the client for action. If the server is 
down or unaccessable, the client will see the console message: 
nd: file server not responding: still trying. 

The client continues (forever) making his request until he gets positive acknowledgement from the server. 
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This means the server can crash or power down and come back up without any special action required of 
the user at the client machine. It also means the process performing the I/O to nd will block, insensitive to 
signals, since the process is sleeping inside the kernel atPRIBIO. 

PROTOCOL AND DRIVER INTERNALS 

The protocol packet is defined in <sun/ndio.h> and also included below: 


/* 

* ‘nd’ protocol packet format. 
*/ 


struct ndpack { 
struct 

ip npip;/* 

ip header, proto IPPROTO_ND *1 

uchar 

npop; 

/* operation code, see below */ 

uchar 

npmin; 

/* minor device */ 

char 

nperror; 

/* b_error */ 

char 

npver; 

/* version number */ 

long 

npseq; 

I* sequence number */ 

long 

npblkno; 

/* b blkno, disk block number */ 

long 

npbcount; 

/* b bcount, byte count */ 

long 

npresid; 

/* b resid, residual byte count *1 

long 

npcaddr; 

1* current byte offset of this packet */ 

long 

npccount; 

/* current byte count of this packet */ 

}; 

/* data follows */ 

/* 

* np oe operation codes. 



*/ 


#define NDOPREAD 

1 

/* read */ 

#define NDOPWRITE 

2 

/* write */ 

#define NDOPERROR 

3 

/* error */ 

#define NDOPCODE 

7 

/* op code mask */ 

#define NDOPWAIT 

010 

/* waiting for DONE or next request */ 

#define NDOPDONE 

1* 

* misc protocol defines. 
*1 

#define NDMAXDATA 

020 

/* operation done */ 

1024 

/* max data per packet */ 

#define NDMAXIO 

63*1024 

/* max np_bcount */ 


BP datagrams were chosen instead of UDP datagrams because only the IP header is checksummed, not the 
entire packet as in UDP. Also the kernel level interface to the IP layer is simpler. The min, blkno, and 
bcount fields are copied directly from the client’s strategy request. The sequence number field seq is incre- 
mented on each new client request and is matched with incoming server responses. The server essentially 
echos the request header in his responses, altering certain fields. The caddr and ccount fields show the 
current byte address and count of the data in this packet, or the data expected to be sent by the other side. 

The protocol is very simple and driven entirely from the client side. As soon as the client ndstrategy rou- 
tine is called, the request is sent to the server; this allows disk sorting to occur at the server as soon as pos- 
sible. Transactions which send data (client writes on the client side, client reads on the server side) can 
only send a set number of packets of NDMAXDATA bytes each, before waiting for an acknowledgement. 
The defaults are currently set at 6 packets of IK bytes each; the NDIOCETHER ioctl allows setting this 
value on the server side. This allows the normal 4K byte case to occur with just one ‘transaction’. The 
NDOPWAIT bit is set in the op field by the sender to indicate he will send no more until acknowledged (or 
requested) by the other side. The NDOPDONE bit is set by the server side to indicate the request operation 
has completed; for both the read and write cases this means the requested disk I/O has actually occured. 
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Requests received by the server are entered on an active list which is timed out and discarded if not com- 
pleted within NDXTIMER seconds. Requests received by the server allocate a bcount size buffer 
minimize buffer copying. Contiguous DMA disk I/O thus occurs in the same size chunks it would 
requested from a local physical disk. 

BOOTSTRAP 

The Sun workstation has PROM code to perform a net boot using this driver. Usually, the boot files are 
obtained from public device 0 (/ dev/ndpO ) on the server with which the client is registered; this allows 
multiple servers to exist on the same net (even running different releases of kernel and boot software). If 
the station you are booting is not registered on any of the servers, you will have to specify the hex Internet 
host number of the server in a boot command string like: ‘bec(0,5,0)vmunix’. 

This booting performs exactly the same steps involved in a real disk boot: 

1) User types ‘b’ to PROM monitor. 

2) PROM loads blocks 1 thru 15 of Idev/ndpO ( bootnd ). 

3) bootnd loads /boot. 

4) / boot loads Ivmunix. 

SEE ALSO 

ioctl(2), nd(8C) 

BUGS 

The operations described in dkio (4) are not supported. 

The local host’s disk buffer cache is not used by network disk access. This means that if either a local host 
or a remote host is writing, the changes will be visible at random based on the cache hit frequency on the 
local host. Use sync on the server to force the data out to disk. If both the local and remote hosts are writ- 
ing to the same filesystem, one machine’s changes can be randomly lost, based again on cache hit and 
deferred write timings. 

If an R/O remote file system is mounted R/W by mistake, it is impossible to umount it. 
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NAME 

nit - Network Interface Tap Protocol 

SYNOPSIS 

options NIT 

DESCRIPTION 

nit is a provisional protocol familty which runs on top of the kernel raw socket code and provides the 
superuser with a tee connection into a specified network interface. For example, it provides the unpro- 
cessed packet read and write capability on the Ethernet interface ie(4S). 

nit uses two structures to communicate information, the nit ioc structure, which contains the ioctl informa- 
tion used to set parameter values; and the nithdr structure, which contains per packet statistics and is 
prepended to every delivered packet When setting parameters, values that are otherwise impossible mean 
"don’t change". 

nit collects incoming packets into chunks to reduce the per packet overhead. The chunks are returned by 
read (2) and recv( 2) system calls. Outgoing packets are not buffered. The ioctl value niocchunksize sets 
the size of the incoming chunk. Niocbufalign and nioc_buf offset control packet placement within buffers. 

The (nit) header for each packet in a buffer starts nioc_buf offset bytes past some multiple of nioc bufalign 
bytes from the beginning. The packet itself appears immediately beyond the header, nit also limits the 
amount of buffer space consumed. To change the default, set nioc bif space. 

nit performs packet filtering and data selection on incoming packets. The data selection criterion is the 
length of the initial portion of the data packet to return to the user. The filtering criteria are packet destina- 
tion and packet type. The filtering and data selection criteria are set via nioc snaplen, nioc Jlags, and 
nioc jypetomatch . The choices for destination are either normal or promiscuous. Normal destination 
filtering considers only those packets that are normally received by the machine running nit (both host 
specific and broadcast packets). Promiscuous destination filtering considers every packet visible on the 
network; this can place a large demand on the processor if there are many packets to receive. The packets 
are further filtered on type, an interface specific quantity. For the Ethernet interfaces, the type field is the 
packet type from the Ethernet header. See <netinet/if_ether.h> . 

Outgoing packets are not (yet) handled in a general way, since there is no one address family which says 
"send the packet as is”, where the data portion of the packet contains a complete packet to be transmitted 
without further processing. Therefore, in general, you can’t send arbitrary packets. For the Ethernet, how- 
ever, the address family AF UNSPEC is defined so that the remaining 14 bytes of the sockaddr correspond 
the the first 14 bytes of the outgoing packet, which are the (6 byte) destination address, the (6 byte) source 
address (possibly overridden), and the (2 byte) type. See struct ether header in <netinet/if ether. c > . 
Therefore, for Ethernet in particular, it is possible to transmit an arbitrary packet. In the example which 
follows, rarp write accepts an arbitrary packet and performs the interface specific manipulations required 
to transmit that packet. 

The following definitions are taken from <net/nit.h> . 

♦define NITIFSIZ 10 /* size of ifname in sockaddr */ 

♦define NITBUFSIZ 1024 /* buffers are rounded up to a 

* multiple of this size (MCLBYTES) */ 

struct sockaddr_nit { 

u_short snit_family; 

caddr_t snit_cookie; /* link to filtering */ 

char snit_ifname [NITIFSIZ] ; /* interface name (eg, ieO) */ 

} ; 


/* Header preceeding each packet returned to user */ 
struct nit_hdr { 

int nh_state; /* state of tap — see below */ 

struct timeval nh_timestamp; /* time of arriving packet */ 
int nh_wirelen; /* length (with header) off wire */ 
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union { 


int 

info; 

/* 

generic information */ 

int 

datalen; 

/* 

length of saved packet portion */ 

int 

dropped; 

/* 

number of dropped matched packets */ 

int 

seqno; 

/* 

sequence number */ 


} nh_un ; 

} ; 

♦define nh_info nh_un.info 

♦define nh_datalen nh_un.datalen 

♦define nh_dropped nh_un . dropped 

♦define nh_seqno nh_un.seqno 

/* Ioctl parameter block */ 
struct nit_ioc { 

int nioc_buf space; /* total buffer space to use */ 

int nioc_chunksize; /* size of chunks to send */ 

u_int nioc_typetomatch; /* magic type with which to match */ 

int nioc_snaplen; /* length of packet portion to snap */ 

int nioc_buf align; /* packet header alignment multiple */ 

int nioc_bufof f set; /* packet header alignment offset */ 

struct timeval nioc_timeout; /* delay after packet before drain */ 
int nioc_flags; /* see below */ 

} ; 

♦define NT_NOTYPES ((u_int)0) /* match no packet types */ 

♦define NT_ALLTYPES (<u_int)-l) /* match all packet types */ 

♦define NF_PROMISC 0x01 /* enter promiscuous mode */ 

♦define NF_T IMEOUT 0x02 /* timeout value valid */ 

♦define NF_BUSY 0x04 /* buffer is busy (has data) */ 

/* 

* States for the packet capture portion of nit, 

* some of which are passed to the user. 

*/ 

♦define NIT_QUIET 0 /* inactive */ 

♦define NIT_CATCH 1 /* capturing packets */ 

♦define NIT_NOMBUF 2 /* discarding — out of mbufs */ 

♦define NIT_NOCLUSTER 3 /* discarding — out of mclusters */ 

♦define NIT_NOSPACE 4 /* discarding — would exceed bufspace */ 

/* Pseudo-states returned in information packets */ 

♦define NIT_SEQN0 5 /* sequence number of chunk */ 

To use nit : 

o Include definitions and declare needed variables, for example 
♦include <sys /types .h> 

♦include <sys/time.h> 

♦include <sys/socket .h> 

♦include <sys/ioctl .h> 

♦include <net/nit.h> 

♦include <net/if.h> 

struct sockaddr_nit snit; 
struct nit ioc nioc; 


Sun Release 3.0 


Last change: 21 November 1985 


325 



NIT (4P) 


SPECIAL FILES 


NIT (4P) 


o Create a socket with the call 

s = socket (AF_NIT, SOCK_RAW, NITPROTO_RAW) ; 

o Bind it to an interface with a code fragment like 
snit . snit_f amily = AF_NIT; 

strncpy (snit . snit_ifname, "ieO", sizeof (snit . snit_ifname) ) ; 
bind (s, (struct sockaddr *) fisnit, sizeof (snit)); 

o To establish the operating modes, issue an iocd; for example 
bzero(&nioc, sizeof (nioc) ) ; 
nioc .nioc_buf space = NITBUFSIZ; 
nioc.nioc_chunksize = NITBUFSIZ; 
nioc.nioc_typetomatch = NT_ALLTYPES ; 
nioc .nioc_snaplen = 32767; 
nioc. nioc_f lags = NF_T IMEOUT ; 
nioc .nioc_timeout .tv_usec = 200; 
if (ioctl (if_fd, SIOCSNIT, Snioc) != 0) { 

perror ( "nit ioctl" ) ; 
exit (2) ; 

} 

o To receive packets, issue reads (or recv s). To transmit packets, issue writes (or sends). For exam- 
ple, the following routine will transmit an arbitrary packet (including address information) on the Eth- 
ernet. Note that the Ethernet addresses and type are provided in the incoming buffer buf, and must be 
moved into the sockaddr destination address to satisfy the kernel. 
rarp_write (fd, buf, len) 
int fd, len; 
char *buf; 

{ 

struct sockaddr sa; 

int offset = sizeof (sa . sa_data) ; 

int result; 


sa.sa_f amily = AF_UNSPEC; 

bcopy (buf, sa . sa_data, offset); 

result = sendto (fd, buf+offset, len-offset, 

0, &sa, sizeof (sa)); 
return ( result +off set) ; 

} 

SEE ALSO 

bind(2), config(8), ec(4S), ie(4S), if(4N), ioctl(2), read(2), recv(2), send(2), socket(2), write(2). 

Network Implementation in Networking on the Sun Workstation. 

BUGS 

This protocol is provisional, and is subject to change. 

Buffering is limited to 32767 bytes. 

Interface ioctl’ s may have different semantics on a nit socket. 
nit is unable to see outgoing transmissions on some interfaces. 

The selection criteria is very simplistic. Therefore, many packets may be passed to the user program, espe- 
cially in promiscuous mode. 
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NAME 

null - data sink 
SYNOPSIS 

None; included with standard system. 

DESCRIPTION 

Data written on a null special file is discarded. 

Reads from a null special file always return an end-of-file indication. 

FILES 

/dev/null 
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NAME 

pty - pseudo terminal driver 

SYNOPSIS 

pseudo-device pty 

DESCRIPTION 

The pty driver provides support for a pair of devices collectively known as a pseudo-terminal. The two 
devices comprising a pseudo-terminal are known as a master and a slave. The slave device provides an 
interface identical to that described in tty{ 4), but instead of having a hardware interface such as the Zilog 
chip and associated hardware used by zs(4S) supporting the terminal functions, the functions of the termi- 
nal are implemented by another process manipulating the master side of the pseudo-terminal. 

The master and the slave sides of the pseudo-terminal are tightly connected. Any data written on the mas- 
ter device is given to the slave device as input, as though it had been received from a hardware interface. 
Any data written on the slave terminal can be read from the master device (rather than being transmitted 
fromaUART). 

In configuring, if no optional “count” is given in the specification, 16 pseudo terminal pairs are 
configured. 

A few special ioctl’s are provided on the control-side devices of pseudo-terminals to provide the func- 
tionality needed by applications programs to emulate real hardware interfaces: 

TIOCSTOP 

Stops output to a terminal (that is, like typing A S). Takes no parameter. 

TIOCSTART 

Restarts output (stopped by TIOCSTOP or by typing A Q). Takes no parameter. 

There are also two independent modes which can be used by applications programs: 

TIOCPKT 

Enable/disable packet mode. Packet mode is enabled by specifying (by reference) a nonzero 
parameter and disabled by specifying (by reference) a zero parameter. When applied to the mas- 
ter side of a pseudo terminal, each subsequent read from the terminal will return data written on 
the slave part of the pseudo terminal preceded by a zero byte (symbolically defined as 
TIOCPKTDATA), or a single byte reflecting control status information. In the latter case, the 
byte is an inclusive-or of zero or more of the bits: 

TIOCPKTFLU SHRE AD 

whenever the read queue for the terminal is flushed. 

TIOCPKTFLU SHWRITE 

whenever the write queue for the terminal is flushed. 

TIOCPKTSTOP 

whenever output to the terminal is stopped a la A S. 

TIOCPKTSTART 

whenever output to the terminal is restarted. 

TIOCPKTDOSTOP 

whenever t stopc is A S and t startc is 'Q. 

TIOCPKTNOSTOP 

whenever the start and stop characters are not 'S/'Q. 

This mode is used by rlo gin (1C) and rlogind( 8C) to implement a remote-echoed, locally 'S/ A Q 
flow-controlled remote login with proper back-flushing of output when interrupts occur; it can be 
used by other similar programs. 

TIOCREMOTE 

A mode for the master half of a pseudo terminal, independent of TIOCPKT. This mode causes 
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BUGS 


input to the pseudo terminal to be flow controlled and not input edited (regardless of the terminal 
mode). Each write to the control terminal produces a record boundary for the process reading the 
terminal. In normal usage, a write of data is like the data typed as a line on the terminal; a write of 
0 bytes is like typing an end-of-file character. TIOCREMOTE can be used when doing remote 
line editing in a window manager, or whenever flow controlled input is required. 

/dev/pty[p-r][0-9a-f] master pseudo terminals 

/dev/tty[p-r] [0-9a-f| slave pseudo terminals 

It is apparently not possible to send an EOT by writing zero bytes in TIOCREMOTE mode. 
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NAME 

routing - system supporting for local network packet routing 
DESCRIPTION 

The network facilities provided general packet routing, leaving routing table maintenance to applications 
processes. 

A simple set of data structures comprise a “routing table” used in selecting the appropriate network inter- 
face when transmitting packets. This table contains a single entry for each route to a specific network or 
host. A user process, the routing daemon, maintains this data base with the aid of two socket specific 
ioctl (2) commands, SIOCADDRT and SIOCDELRT. The commands allow the addition and deletion of a 
single routing table entry, respectively. Routing table manipulations may only be carried out by super-user. 

A routing table entry has the following form, as defined in <net/route.h> : 
struct rtentry { 

ulong rt hash; 
struct sockaddr rtdst; 

struct sockaddr rtgateway; 

short rtflags; 
short rtrefcnt; 
u long rt use; 
struct ifnet *rt_ifp; 

}; 

with rt Jiags defined from: 


#define RTF UP 

0x1 

/* route usable */ 

#define RTF GATEWAY 

0x2 

/* destination is a gateway */ 

#define RTF HOST 

0x4 

/* host entry (net otherwise) */ 


Routing table entries come in three flavors: for a specific host, for all hosts on a specific network, for any 
destination not matched by entries of the first two types (a wildcard route). When the system is booted, 
each network interface autoconfigured installs a routing table entry when it wishes to have packets sent 
through it. Normally the interface specifies the route through it is a “direct” connection to the destination 
host or network. If the route is direct, the transport layer of a protocol family usually requests the packet 
be sent to the same host specified in the packet. Otherwise, the interface may be requested to address the 
packet to an entity different from the eventual recipient (i.e. the packet is forwarded). 

Routing table entries installed by a user process may not specify the hash, reference count, use, or interface 
fields; these are filled in by the routing routines. If a route is in use when it is deleted ( rt refcnt is non- 
zero), the resources associated with it will not be reclaimed until all references to it are removed. 

The routing code returns EEXIST if requested to duplicate an existing entry, ESRCH if requested to delete 
a non-existant entry, or ENOBUFS if insufficient resources were available to install a new route. 

User processes read the routing tables through the Idevlkmem device. 

The rt use field contains the number of packets sent along the route. This value is used to select among 
multiple routes to the same destination. When multiple routes to the same destination exist, the least used 
route is selected. 

A wildcard routing entry is specified with a zero destination address value. Wildcard routes are used only 
when the system fails to find a route to the destination host and network. The combination of wildcard 
routes and routing redirects can provide an economical mechanism for routing traffic. 

SEE ALSO 

route(8C), routed(8C) 
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NAME 

sd - Disk driver for Adaptec ST-506 Disk Controllers 
SYNOPSIS — SUN-3 

controller scO at vme24dl6 ? csr 0x200000 priority 2 vector scintr 0x40 

controller siO at vme24dl6 ? csr 0x200000 priority 2 vector siintr 0x40 

controller siO at obio ? csr 0x140000 priority 2 

disk sdO at scO drive 0 flags 0 

disk sdl at scO drive 1 flags 0 

disk sdO at siO drive 0 flags 0 

disk sdl at siO drive 1 flags 0 

The first two controller lines above specify the first SCSI controller on a Sun-3/160. The third controller 
line above specifies the first and only SCSI controller on a Sun-3/50. The four disk lines specify the first 
and second disk drives on the first SCSI controller in a system. 

SYNOPSIS — SUN-2 

controller scO at mbmem ? csr 0x80000 priority 2 

controller scl at mbmem ? csr 0x84000 priority 2 

controller scO at vme24 ? csr 0x200000 priority 2 vector scintr 0x40 

disk sdO at scO drive 0 flags 0 

disk sdl at scO drive 1 flags 0 

disk sd2 at scl drive 0 flags 0 

disk sd3 at scl drive 1 flags 0 

The first two controller lines above specify the first and second SCSI controllers on a Sun-2/120 or Sun- 
2/170. The third controller line above specifies the first controller on a Sun-2/160. The four disk lines 
specify the first and second disk drives on the first and second SCSI controllers in a system. 

DESCRIPTION 

Files with minor device numbers 0 through 7 refer to various portions of drive 0. The standard device 
names begin with “sd” followed by the drive number and then a letter a-h for partitions 0-7 respectively. 
The character ? stands here for a drive number in the range 0-7. 

The block file’s access the disk via the system’s normal buffering mechanism and may be read and written 
without regard to physical disk records. There is also a ‘raw’ interface which provides for direct transmis- 
sion between the disk and the user’s read or write buffer. A single read or write call usually results in one 
I/O operation; therefore raw I/O is considerably more efficient when many words are transmitted. The 
names of the raw files conventionally begin with an extra ‘r.’ 

In raw I/O, requests to the SCSI disk must have an offset on a 512 byte boundary, and their length must be a 
multiple of 512 bytes or the driver will return an error (EENVAL). Likewise seek calls should specify a 
multiple of 512 bytes. 

DISK SUPPORT 

This driver handles all ST-506 drives, by reading a label from sector 0 of the drive which describes the disk 
geometry and partitioning. 

The sd?a partition is normally used for the root file system on a disk, the sd?b partition as a paging area, 
and the sd?c partition for pack-pack copying (it normally maps the entire disk). The rest of the disk is nor- 
mally the sd?g partition. 

FILES 

/dev/sd[0-7][a-h] block files 

/dev/rsd[0-7][a-h] raw files 

SEE ALSO 

dkio(4S) 

Adaptec ACB 4000 and 5000 Series Disk Controllers OEM Manual 
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DIAGNOSTICS 

sd%d%c: cmd how (msg) blk %d. A command such as read or write encountered a error condition 
(how): either ii failed, the unit was restored, or an operation was retry' ed. The msg is derived from the 
error number given by the controller, indicating a condition such as “drive not ready” or “sector not 
found”. 
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NAME 

st - Driver for Sysgen SC 4000 (Archive) and the Emulex MT-02 Tape Controller 
SYNOPSIS — SUN-3 

controller scO at vme24dl6 ? csr 0x200000 priority 2 vector scintr 64 
controller siO at vme24dl6 ? csr 0x200000 priority 2 vector siintr 64 
controller siO at obio ? csr 0x140000 priority 2 
tape stO at scO drive 32 flags 1 
tape stO at siO drive 32 flags 1 

The first two controller lines above specify the first SCSI controller on a Sun-3/160. The third controller 
line above specifies the first and only SCSI controller on a Sun-3/50. The four tape lines specify the first 
and second tape drives on the first SCSI controller in a system. 

SYNOPSIS — SUN-2 

controller scO at mbmem ? csr 0x80000 priority 2 

controller scO at vme24 ? csr 0x200000 priority 2 vector scintr 64 

controller scl at mbmem ? csr 0x84000 priority 2 

tape stO at scO drive 32 flags 1 

tape stl at scl drive 32 flags 1 

The first two controller lines above specify the first and second SCSI controllers on a Sun-2/120 or Sun- 
2/170. The third controller line above specifies the first controller on a Sun-2/160. The four tape lines 
specify the first and second tape drives on the first and second SCSI controllers in a system. 

DESCRIPTION 

In the synopsis lines above, the first line specifies the first SCSI controller on a Sun-2/ 120 or Sun-2/ 170; the 
second specifies the first such controller on a Sun-2/160; the third specifies the first SCSI controller on a 
Sun-3/160; the fourth specifies the first and only SCSI controller on a Sun-3/50. The last two lines specify 
the first tape drive on the first SCSI controller in a system. 

The Sysgen tape controller is a SCSI bus interface to an Archive streaming tape drive. It provides a stan- 
dard tape interface to the device, see mtio{ 4), with some deficiencies listed under BUGS below. To utilize 
the QIC 24 format, access the logical device that is eight more than the default physical (QIC 11) device 
(that is, rstO = QIC 11, rst8 = QIC 24). 


FILES 

/dev/rst[0-3] 

/dev/rst[8-ll] 

/dev/nrst[0-3] 

/dev/nrst[8-ll] 


QIC 1 1 Format 
QIC 24 Format 
non-rewinding QIC 11 Format 
non-rewinding QIC 24 Format 


SEE ALSO 

mtio(4) 

Sysgen SC4000 Intelligent Tape Controller Product Specification 

Archive Intelligent Tape Drive Theory of Operation, Archive Corporation (Sun 8000-1058-01) 
Archive Product Manual (Sidewinder 1/4" Streaming Cartridge Tape Drive) (Sun 800-0628-01) 
Emulex MT02 Tape Controller Technical Manual 


DIAGNOSTICS 

st*: tape not online. 

st*: no cartridge in drive, 
st*: cartridge is write protected, 
st*: format change failed, 
st*: device not supported. 
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BUGS 

The tape cannot reverse direction so the BSF and BSR ioctls are not supported. 

The FSR ioctl is not supported. 

Most disk I/O over the SCSI bus is prevented when the tape is in use. This is because the controller does 
not free the bus while the tape is in motion (even during rewind). 

When using the raw device, the number of bytes in any given transfer must be a multiple of 512. If it is 
not, the device driver returns an error. 

The driver will only write an end of file mark on close if the last operation was a write, without regard for 
the mode used when opening the file. This will cause empty files to be deleted on a raw tape copy opera- 
tion. 

Some older systems may not support the QIC 24 device, and may complain (or exhibit erratic behavior) 
when the user attempts a QIC 24 device access. 
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NAME 

top - Internet Transmission Control Protocol 
STNOPSIS 

None; included automatically with inet(4 F). 

DESCRIPTION 

TCP is a connection-oriented, end-to-end reliable protocol designed to fit into a layered hierarchy of proto- 
cols which support multi-network applications. TCP provides for reliable inter-process communication 
between pairs of processes in host computers attached to distinct but interconnected computer communica- 
tion networks. Very few assumptions are made as to the reliability of the communication protocols below 
TCP layer. TCP assumes it can obtain a simple, potentially unreliable datagram service from the lower 
level protocols. In principle, TCP should be able to operate above a wide spectrum of communication sys- 
tems ranging from hard-wired connections to packet-switched or circuit switched networks. 

TCP fits into a layered protocol architecture just above the basic Internet Protocol (IP) described in ip{ 4P) 
which provides a way for TCP to send and receive variable-length segments of information enclosed in 
Internet datagram “envelopes.” The Internet datagram provides a means for addressing source and desti- 
nation TCPs in different networks, deals with any fragmentation or reassembly of the TCP segments 
required to achieve transport and delivery through multiple netwokrs and interconnecting gateways, and 
has the ability to carry information on the precedence, security classification and compartmentalization of 
the TCP segments (although this is not currently implemented under the UNIX system.) 

An application process interfaces to TCP through the socket ( 2) abstraction and the related calles bind (2), 
listen(2), accept(2), connect (2), send (2) and recv(2). The primary purpose of TCP is to provide a reliable 
bidirectional virtual circuit service between pairs of processes. In general, the TCP’s decide when to block 
and forward data at their own convenience. In the UNIX system implementation, it is assumed that any 
buffering of data is done at the user level, and the TCP’s transmit available data as soon as possible to their 
remote peer. They do this and always set the PUSH bit indicating that the transferred data should be made 
available to the user process at the remote end as soon as practicable. 

To provide reliable data TCP must recover from data that is damaged, lost, duplicated, or delivered out of 
order by the underlying internet communications system. This is achieved by assigning a sequence number 
to each byte of data transmitted and requiring a positive acknowledgement from the receiving TCP. If the 
ACK is not received within an (adaptively determined) timeout interval, the data is retransmitted. At the 
receiver, the sequence numbers are used to correctly order segments that may be received out of order and 
to eliminate duplicates. Damage is handled by adding a checksum to each segment transmitted, checking it 
at the receiver, and discarding damaged segments. As long as the TCP’s continue to function properly and 
the internet system does not become disjoint, no tranmission errors will affect the correct delivery of data, 
as TCP recovers from communications errors. 

TCP provides flow control over the transmitted data. The receiving TCP is allowed to specify the amount 
of data which may be sent by the sender, by returning a window with every acknowledgement indicating a 
range of acceptable sequence numbers beyond the last segment successfully received. The window indi- 
cates an allowed number of bytes that the sender may transmit before receiving further permission. 

TCP extends the standard 32-bit Internet host addresses with a 16-bit port number space; the combined 
addresses are available at the UNIX system process level in the standard sockaddrjn format described in 
inet(4 F). 

Sockets utilizing the top protocol are either “active” or “passive”. Active sockets initiate connections to 
passive sockets. By default TCP sockets are created active; to create a passive socket the listen{ 2) system 
call must be used after binding the socket to an address with the bind (2) system call. Only passive sockets 
may use the accept(2) call to accept incoming connections. Only active sockets may use the connect (2) 
call to initiate connections. 

Passive sockets may “underspecify” their location to match incoming connection requests from multiple 
networks. This technique, termed “wildcard addressing”, allows a single server to provide service to 
clients on multiple networks. To create a socket which listens on all networks, the Internet address 
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INADDR ANY must be bound. The TCP port may still be specified at this time; if the port is not specified 
the system will assign one. Once a connection has been established the socket’s address is fixed by the 
peer entity s location. The address assigned the socket is the address associated with the network interface 
through which packets are being transmitted and received. Normally this address corresponds to the peer 
entity’s network. See inet{ 4F) for a complete description of addressing in the Internet family. 

A TCP connection is created at the server end by doing a socket( 2), a bind( 2) to establish the address of the 
socket, a listen (2) to cause connection queueing, and then an accept (2) which returns the descriptor for the 
socket. A client connects to the server by doing a socket (2) and then a connect (2). Data may then be sent 
from server to client and back using read (2) and write (2). 

TCP implements a very weak out-of-band mechanism, which may be invoked using the out-of-band provi- 
sions of send(2). This mechanism allows setting an urgent pointer in the data stream; it is reflected to the 
TCP user by making the byte after the urgent pointer available as out-of-band data and providing a 
SIOCATMARK ioctl which returns an integer indicating whether the stream is at the urgent mark. The 
system never returns data across the urgent mark in a single read. Thus, when a SIGURG signal is 
received indicating the presence of out-of-band data, and the out-of-band data indicates that the data to the 
mark should be flushed (as in remote terminal processing), it suffices to loop, checking whether you are at 
the out-of-band mark, and reading data while you are not at the mark. 

SEE ALSO 

inet(4F), ip(4P) 

BUGS 

It should be possible to send and receive TCP options. 

The system always tries to negotiates the maximum TCP segment size to be 1024 bytes. This can result in 
poor performance if an intervening network performs excessive fragmentation. 

SIOCSHIWAT and SIOCGHIWAT ioctl’s to set and get the high water mark for the socket queue, and so 
that it can be changed from 2048 bytes to be larger or smaller, have been defined (in <sys/ioctl.h>) but not 
implemented. 
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NAME 

tm - tapemaster 1/2 inch tape drive 
SYNOPSIS — SUN-3 

controller tmO at vmel6dl6 ? csr OxaO priority 3 vector tmintr 96 
controller tml at vmel6dl6 ? csr 0xa2 priority 3 vector tmintr 97 
tape mtO at tmO drive 0 flags 1 
tape mtO at tml drive 0 flags 1 

SYNOPSIS — SUN-2 

controller tmO at mbio ? csr OxaO priority 3 

controller tmO at vmel6 ? csr OxaO priority 3 vector tmintr 96 

controller tml at mbio ? csr 0xa2 priority 3 

controller tml at vme!6 ? csr 0xa2 priority 3 vector tmintr 97 

tape mtO at tmO drive 0 flags 1 

tape mtO at tml drive 0 flags 1 

DESCRIPTION 

The Tapemaster tape controller controls Pertec-interface 1/2" tape drives such as the CDC Keystone, pro- 
viding a standard tape interface to the device, see mtio( 4). 

SEE ALSO 

mt(l), tar(l), ar(4S) 

CPC Tapemaster Product Specification (Sun 800-0620-01) 

CPC Tapemaster Application Note (Sun 800-0622-01) 

CDC Streaming Tape Unit 9218X Reference Manual (Sun 800-0623-01) 

DIAGNOSTICS 

tm%d: no response from ctlr. 
tm%d: error %d during config. 
mt%d: not online. 
mt%d: no write ring. 

tmgo: gate wasn’t open. Controller lost synch, 
tmintr: can’t clear interrupts. 
tm%d: stray interrupts. 
mt%d: hard error bn=%d er=%x. 
mt%d: lost interrupt. 

BUGS 

The Tapemaster controller does not provide for byte-swapping and the resultant system overhead prevents 
streaming transports from streaming. 

If a non-data error is encountered on non-raw tape, it refuses to do anything more until closed. 

The system should remember which controlling terminal has the tape drive open and write error messages 
to that terminal rather than on the console. 
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NAME 

tty - general terminal interface 
SYNOPSIS 

None; included by default. 

DESCRIPTION 

This section describes the special file /dev/tty and the terminal drivers used for conversational computing 
by serial interfaces such as z$(4S), conj(4S), and pty(4). 

Line disciplines. 

The system provides different line disciplines for controlling communications lines. In this version of the 
system there are three disciplines available: 

old The old (standard) terminal driver. This is used when using the standard shell sh(l) and for com- 
patibility with Version 7 UNIX systems. 

new A newer terminal driver, with features for job control; this must be used when using csh( 1). 

net A line discipline used for networking and loading data into the system over communications 

lines. It allows high speed input at very low overhead, and is described in bk(4). 

Line discipline switching is accomplished with the TIOCSETD ioctl: 

int ldisc = LDISC; ioctl(f, TIOCSETD, &ldisc); 

where LDISC is OTTYDISC for the standard tty driver, NTTYDISC for the new driver and NETLDISC 
for the networking discipline. The standard (currently old) tty line discipline is 0 by convention. The 
current line discipline can be obtained with the TIOCGETD ioctl. Pending input is discarded when the line 
discipline is changed. 

All of the low-speed asynchronous communications ports can use any of the available line disciplines, no 
matter what hardware is involved. The remainder of this section discusses the “old” and “new” discip- 
lines. 

The control terminal. 

When a terminal file is opened, it causes the process to wait until a connection is established. In practice, 
user programs seldom open these files; they are opened by inif(8) and become a user’s standard input and 
output file. 

If a process which has no control terminal opens a terminal file, then that terminal file becomes the control 
terminal for that process. The control terminal is thereafter inherited by a child process, during a fork (2), 
even if the control terminal is closed. 

The file /dev/tty is, in each process, a synonym for a control terminal associated with that process. It is 
useful for programs that wish to be sure of writing messages on the terminal no matter how output has been 
redirected. It can also be used for programs that demand a file name for output, when typed output is 
desired and it is tiresome to find out which terminal is currently in use. 

A process can remove the association it has with its controlling terminal by opening the file /dev/tty and 
issuing a 

ioctl(f, TTOCNOTTY, 0); 

This is often desirable in server processes. 

Process groups. 

Command processors such as csh(l) can arbitrate the terminal between different jobs by placing related 
jobs in a single process group and associating this process group with the terminal. A terminal’s associated 
process group may be set using the TIOCSPGRP ioctl( 2): 

ioctl(fildes, TIOCSPGRP, &pgrp) 
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or examined using TIOCGPGRP, which returns the current process group in pgrp. The new terminal driver 
aids in this arbitration by restricting access to the terminal by processes which are not in the current process 
group; see Job access control below. 

Modes. 

The terminal line disciplines have three major modes, characterized by the amount of processing on the 
input and output characters: 

cooked The normal mode. In this mode lines of input are collected and input editing is done. The 
edited line is made available when it is completed by a newline or when the t_brkc character, 
normally an EOT (control-D, hereafter A D), is entered. A carriage return is usually made 
synonymous with newline in this mode, and replaced with a newline whenever it is typed. All 
line discipline functions (input editing, interrupt generation, output processing such as delay 
generation and tab expansion, etc.) are available in this mode. 

CBREAK This mode eliminates the character, word, and line editing input facilities, making the input 
character available to the user program as it is typed. Flow control, literal-next and interrupt 
processing are still done in this mode. Output processing is done. 

RAW This mode eliminates all input processing and makes all input characters available as they are 
typed; no output processing is done either. 

The style of input processing can also be very different when the terminal is put in non-blocking i/o mode; 
see the FNDELAY flag as described in fcntl(2). In this case a re ad (2) from the control terminal will never 
block, but rather return an error indication (EWOULDBLOCK) if there is no input available. 

A process may also request a SIGIO signal be sent it whenever input is present To enable this mode the 
FASYNC flag should be set using fcntl (2). 

Input editing. 

A UNIX system terminal ordinarily operates in full-duplex mode. Characters may be typed at any time, 
even while output is occurring, and are only lost when the system’s character input buffers become com- 
pletely choked, which is rare, or when the user has accumulated the maximum allowed number of input 
characters that have not yet been read by some program. Currently this limit is 256 characters. In the old 
terminal line discipline all the saved characters are thrown away without notice when the limit is reached; 
in RAW or CBREAK mode, the new line discipline throws away all input and output, but in cooked mode 
it refuses to accept any further input and rings the terminal bell. 

Input characters are normally accepted in either even or odd parity with the parity bit being stripped off 
before the character is given to the program. By clearing either the EVEN or ODD bit in the flags word it 
is possible to have input characters with that parity discarded (see the Summary below.) 

In all of the line disciplines, it is possible to simulate terminal input using the TIOCSTI ioctl, which takes, 
as its third argument, the address of a character. The system pretends that this character was typed on the 
argument terminal, which must be the control terminal except for the super-user (this call is not in standard 
Version 7 UNIX system). 

Input characters are normally echoed by putting them in an output queue as they arrive. This may be dis- 
abled by clearing the ECHO bit in the flags word using the stty( 3C) call or the TIOCSETN or TIOCSETP 
ioctls (see the Summary below). 

In cooked mode, terminal input is processed in units of lines. A program attempting to read will normally 
be suspended until an entire line has been received (but see the description of SIG l'llN in Modes above 
and FIONREAD in Summary below.) No matter how many characters are requested in the read call, at 
most one line will be returned. It is not, however, necessary to read a whole line at once; any number of 
characters may be requested in a read, even one, without losing information. 

During input, line editing is normally done, with the DELETE character logically erasing the last character 
typed and a TJ (control-U) logically erasing the entire current input line. These characters never erase 
beyond the beginning of the current input line or an T>. These characters may be entered literally by 
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preceding them with in the old teletype line discipline both the ‘\ ’ and the character entered literally 
will appear on the screen; in the new line discipline the ‘\ ’ will normally disappear. 

The line disciplines normally treat either a carriage return or a newline character as terminating an input 
line, replacing the return with a newline and echoing a return and a line feed. If the CRMOD bit is cleared 
in the local mode word then the processing for carriage return is disabled, and it is simply echoed as a 
return, and does not terminate cooked mode input. 

discipline ^ is a “teral-next character 'V which can be typed in both cooked and 
CBREAR mode preceding any character to prevent its special meaning. This is to be prefeired to the use 

of \ escaping erase and kill characters, but ‘\ ’ is (at least temporarily) retained with its old function in the 
new line discipline. 

The new terminal line discipline also provides two other editing characters in normal mode. The word- 
erase character, normally A W, erases the preceding word, but not any spaces before it For the purposes of 
W, a word is defined as a sequence of non-blank characters, with tabs counted as blanks. Finally the 
reprint character, normally 'R, retypes the pending input beginning on a new line. Retyping occurs 
automatically in cooked mode if characters which would normally be erased from the screen are fouled bv 
program output. 3 

Input echoing and redisplay 

In the old terminal line discipline, nothing special occurs when an erase character is typed; the erase char- 
acter is simply echoed. When a kill character is typed it is echoed followed by a new-line (even if the char- 
acter is not killing the line, because it was preceded by a ‘\ ’). 

The new terminal line discipline has several modes for handling the echoing of terminal input, controlled 
by bits in a local mode word. 

Hardcopy terminals. When a hardcopy terminal is in use, the LPRTERA bit is normally set in the local 
mode word. Characters which are logically erased are then printed out backwards preceded by ‘\ ’ and fol- 
lowed by 7’ in this mode. 

Crt terminals. When a crt terminal is in use, the LCRTBS bit is normally set in the local mode word. The 
terminal line discipline then echoes the proper number of backspace characters when input is erased to 

reposition the cursor. If the input has become fouled due to interspersed asynchronous output, the input is 
automatically retyped. 

Erasing characters from a crt. When a crt terminal is in use, the LCRTERA bit may be set to cause input to 
be erased from the screen with a “backspace-space-backspace” sequence when character or word deleting 
sequences are used. A LCRTKIL bit may be set as well, causing the input to be erased in this manner on 
line kill sequences as well. 

Echoing of control characters. If the LCTLECH bit is set in the local state word, then non-printing (con- 
trol) characters are normally echoed as A X (for some X) rather than being echoed unmodified; delete is 
echoed as A ?. 

The normal modes for using the new terminal line discipline on crt terminals are speed dependent At 
speeds less than 1200 baud, the LCRTERA and LCRTKILL processing is painfully slow, so j«y(l) nor- 
mally just sets LCRTBS and LCTLECH; at speeds of 1200 baud or greater all of these bits are normally 
set The .r«y(l) command summarizes these option settings and the use of the new terminal line discipline 
as “newcrt.” 

Output processing. 

When one or more characters are written, they are actually transmitted to the terminal as soon as 
previously-written characters have finished typing. (As noted above, input characters are normally echoed 
by putting them in the output queue as they arrive.) When a process produces characters more rapidly than 
they can be typed, it will be suspended when its output queue exceeds some limit. When the queue has 
drained down to some threshold the program is resumed. Even parity is normally generated on output. 
The EOT character is not transmitted in cooked mode to prevent terminals that respond to it from hanging 
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up; programs using raw or cbreak mode should be careful. 

The terminal line disciplines provide necessary processing for cooked and CBREAK mode output includ- 
ing delay generation for certain special characters and parity generation. Delays are available after back- 
spaces A H, form feeds A L, carriage returns A M, tabs A I and newlines A J. The line disciplines will also option- 
ally expand tabs into spaces, where the tab stops are assumed to be set every eight columns. These func- 
tions are controlled by bits in the tty flags word; see Summary below. 

The terminal line disciplines provide for mapping between upper and lower case on terminals lacking 
lower case, and for other special processing on deficient terminals. 

Finally, in the new terminal line discipline, there is an output flush character, normally A 0, which sets the 
LFLUSHO bit in the local mode word, causing subsequent output to be flushed until it is cleared by a pro- 
gram or more input is typed. This character has effect in both cooked and CBREAK modes and causes 
pending input to be retyped if there is any pending input. An ioctl to flush the characters in the input and 
output queues, TIOCFLUSH, is also available. 

Upper case terminals and Hazeltines 

If the LCASE bit is set in the tty flags, then all upper-case letters are mapped into the corresponding 
lower-case letter. The upper-case letter may be generated by preceding it by V. If the new terminal line 
discipline is being used, then upper case letters are preceded by a ‘\ ’ when output In addition, the follow- 
ing escape sequences can be generated on output and accepted on input: 

for ' | ' { } 

use \' \ ! \ A \( \) 

To deal with Hazeltine terminals, which do not understand that " has been made into an ASCII character, 
the LTILDE bit may be set in the local mode word when using the new terminal line discipline; in this case 
the character " will be replaced with the character ' on output. 

Flow control. 

There are two characters (the stop character, normally A S, and the start character, normally A Q) which cause 
output to be suspended and resumed respectively. Extra stop characters typed when output is already 
stopped have no effect, unless the start and stop characters are made the same, in which case output 
resumes. 

A bit in the flags word may be set to put the terminal into TANDEM mode. In this mode the system pro- 
duces a stop character (default A S) when the input queue is in danger of overflowing, and a start character 
(default A Q) when the input has drained sufficiently. This mode is useful when the terminal is actually 
another machine that obeys the conventions. 

Line control and breaks. 

There are several ioctl calls available to control the state of the terminal line. The TIOCSBRK ioctl will set 
the break bit in the hardware interface causing a break condition to exist; this can be cleared (usually after 
a delay with sleep ( 3)) by TIOCCBRK. Break conditions in the input are reflected as a null character in 
RAW mode or as the interrupt character in cooked or CBREAK mode. The TIOCCDTR ioctl will clear 
the data terminal ready condition; it can be set again by TIOCSDTR. 

When the carrier signal from the dataset drops (usually because the user has hung up his terminal) a 
SIGHUP hangup signal is sent to the processes in the distinguished process group of the terminal; this usu- 
ally causes them to terminate (the SIGHUP can be suppressed by setting the LNOHANG bit in the local 
state word of the driver.) Access to the terminal by other processes is then normally revoked, so any 
further reads will fail, and programs that read a terminal and test for end-of-file on their input will ter- 
minate appropriately. 

When using an ACU it is possible to ask that the phone line be hung up on the last close with the 
TIOCHPCL ioctl; this is normally done on the outgoing line. 
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Interrupt characters. 

There are several characters that generate interrupts in cooked and CBREAK mode; all are sent to the 
processes in the control group of the terminal, as if a TIOCGPGRP ioctl were done to get the process group 
and then a killpg{ 2) system call were done, except that these characters also flush pending input and output 
when typed at a terminal (a la TIOCFLUSH). The characters shown here are the defaults; the field names 
in the structures (given below) are also shown. The characters may be changed. 

C t_intrc (ETX) generates a SIGINT signal. This is the normal way to stop a process which is no 
longer interesting, or to regain control in an interactive program. 

*\ t_quitc (FS) generates a SIGQUIT signal. This is used to cause a program to terminate and pro- 
duce a core image, if possible, in the file core in the current directory. 

Z t_suspc (EM) generates a SIGTSTP signal, which is used to suspend the current process group. 

Y t_dsuspc (SUB) generates a SIGTSTP signal as “Z does, but the signal is sent when a program 
attempts to read the ‘Y, rather than when it is typed. 

Job access control. 

When using the new terminal line discipline, if a process which is not in the distinguished process group of 
its control terminal attempts to read from that terminal its process group is sent a SIGTTIN signal. This 
signal normally causes the members of that process group to stop. If, however, the process is ignoring 
SIGTTIN, has SIGTTIN blocked, is an orphan process , or is in the middle of process creation using 
vfork( 2)), it is instead returned an end-of-file. (An orphan process is a process whose parent has exited and 
has been inherited by the init{ 8) process.) Under older UNIX systems these processes would typically have 
had their input files reset to /dev/null, so this is a compatible change. 

When using the new terminal line discipline with the LTOSTOP bit set in the local modes, a process is 
prohibited from writing on its control terminal if it is not in the distinguished process group for that termi- 
nal. Processes which are holding or ignoring SIGTTOU signals, which are orphans, or which are in the 
middle of a vfork( 2) are excepted and allowed to produce output. 

Summary of modes. 

Unfortunately, due to the evolution of the terminal drivers and line disciplines, there are 4 different struc- 
tures which contain various portions of the driver and line discipline data. The first of these (sgttyb) con- 
tains that part of the information largely common between Version 6 and Version 7 UNIX systems. The 
second contains additional control characters added in Version 7. The third is a word of local state peculiar 
to the new terminal line discipline, and the fourth is another structure of special characters added for the 
new line discipline. In the future a single structure may be made available to programs which need to 
access all this information; most programs need not concern themselves with all this state. 

Basic modes: sgtty. 

The basic ioctl s use the structure defined in < sgtty. h>: 

struct sgttyb { 

char sg_ispeed; 
char sg_ospeed; 
char sg_erase; 
char sg_kill; 
short sg_flags; 

}; 

The sgjspeed and sg ospeed fields describe the input and output speeds of the device according to the fol- 
lowing table, which corresponds to the DEC DH-11 interface. If other hardware is used, impossible speed 
changes are ignored. Symbolic values in the table are as defined in <sys/ttydev.h > . 


BO 

0 

(hang up dataphone) 

B50 

1 

50 baud 

B75 

2 

75 baud 
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B110 

3 

1 10 baud 

B134 

4 

134.5 baud 

B150 

5 

150 baud 

B200 

6 

200 baud 

B300 

7 

300 baud 

B600 

8 

600 baud 

B1200 

9 

1200 baud 

B1800 

10 

1800 baud 

B2400 

11 

2400 baud 

B4800 

12 

4800 baud 

B9600 

13 

9600 baud 

EXTA 

14 

19200 baud 

EXTB 

15 

External B 


In the current configuration, only 110, 150, 300 and 1200 baud are really supported on dial-up lines. Code 
conversion and line control required for IBM 2741’s (134.5 baud) must be implemented by the user’s pro- 
gram. The half-duplex line discipline required for the 202 dataset (1200 baud) is not supplied; full-duplex 
212 datasets work fine. 

The sg_erase and sgjcill fields of the argument structure specify the erase and kill characters respectively. 
(Defaults are DELETE and TJ.) 

The sgjlags field of the argument structure contains several bits that determine the system’s treatment of 


the terminal: 

ALLDELAY 

0177400 Delay algorithm selection 

BSDELAY 

0100000 Select backspace delays (not implemented): 

BS0 

0 

BS1 

0100000 

VTDELAY 

0040000 Select form-feed and vertical-tab delays: 

FF0 

0 

FF1 

0100000 

CRDELAY 

0030000 Select carriage-return delays: 

CR0 

0 

CR1 

0010000 

CR2 

0020000 

CR3 

0030000 

TBDELAY 

0006000 Select tab delays: 

TAB0 

0 

TAB1 

0001000 

TAB2 

0004000 

XTABS 

0006000 

NLDELAY 

0001400 Select new-line delays: 

NL0 

0 

NL1 

0000400 

NL2 

0001000 

NL3 

0001400 

EVENP 

0000200 Even parity allowed on input (most terminals) 

ODDP 

0000100 Odd parity allowed on input 

RAW 

0000040 Raw mode: wake up on all characters, 8-bit interface 

CRMOD 

0000020 Map CR into LF; echo LF or CR as CR-LF 

ECHO 

0000010 Echo (full duplex) 

LCASE 

0000004 Map upper case to lower on input 

CBREAK 

0000002 Return each character as soon as typed 

TANDEM 

0000001 Automatic flow control 
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The delay bits specify how long transmission stops to allow for mechanical or other movement when cer- 
tain characters are sent to the terminal. In all cases a value of 0 indicates no delay. 

Backspace delays are currently ignored but might be used for Terminet 300’s. 

If a form-feed/vertical tab delay is specified, it lasts for about 2 seconds. 

Carriage-return delay type 1 lasts about .08 seconds and is suitable for the Terminet 300. Delay type 2 
lasts about .16 seconds and is suitable for the VT05 and the TI 700. Delay type 3 is suitable for the 
concept- 100 and pads lines to be at least 9 characters at 9600 baud. 

New-line delay type 1 is dependent on the current column and is tuned for Teletype model 37 ’s. Type 2 is 
useful for the VT05 and is about .10 seconds. Type 3 is unimplemented and is 0. 

Tab delay type 1 is dependent on the amount of movement and is tuned to the Teletype model 37. Type 3, 
called XTABS, is not a delay at all but causes tabs to be replaced by the appropriate number of spaces on 
output. 

Input characters with the wrong parity, as determined by bits 200 and 100, are ignored in cooked and 
CBREAK mode. 

RAW disables all processing save output flushing with LFLUSHO; full 8 bits of input are given as soon as 
it is available; all 8 bits are passed on output. A break condition in the input is reported as a null character. 
If the input queue overflows in raw mode it is discarded; this applies to both new and old line discipline. 

CRMOD causes input carriage returns to be turned into new-lines; input of either CR or LF causes LF-CR 
both to be echoed (for terminals with a new-line function). 

CBREAK is a sort of half-cooked (rare?) mode. Programs can read each character as soon as typed, 
instead of waiting for a full line; all processing is done except the input editing: character and word erase 
and line kill, input reprint, and the special treatment of \ or EOT are disabled. 

TANDEM mode causes the system to produce a stop character (default A S) whenever the input queue is in 
danger of overflowing, and a start character (default A Q) when the input queue has drained sufficiently. It 
is useful for flow control when the ‘terminal’ is really another computer which understands the conven- 
tions. 

Note: The same stop- and start-characters are used for both direction on the tty line. 

Basic ioctls 

In addition to the TIOCSETD and TIOCGETD disciplines discussed in Line disciplines above, a large 
number of other ioctl(2) calls apply to terminals, and have the general form: 

#include <sgtty.h> 

ioctI(fildes, code, arg) 
struct sgttyb *arg; 

The applicable codes are: 

TIOCGETP Fetch the basic parameters associated with the terminal, and store in the pointed-to 
sgttyb structure. 

TIOCSETP Set the parameters according to the pointed-to sgttyb structure. The interface delays 
until output is quiescent, then throws away any unread characters, before changing the 
modes. 

TIOCSETN Set the parameters like TIOCSETP but do not delay or flush input. Input is not 
preserved, however, when changing to or from RAW. 

With the following codes the arg is ignored. 

TIOCEXCL Set “exclusive-use” mode: no further opens are permitted until the file has been closed. 
TIOCNXCL Turn off “exclusive-use” mode. 
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TIOCHPCL When the file is closed for the last time, hang up the terminal. This is useful when the 
line is associated with an ACU used to place outgoing calls. 

TIOCFLUSH All characters waiting in input or output queues are flushed. 

The remaining calls are not available in vanilla Version 7 UNIX systems. In cases where arguments are 
required, they are described; arg should otherwise be given as 0. 

TIOCSTI the argument is the address of a character which the system pretends was typed on the 

terminal. 

TIOCSBRK the break bit is set in the terminal. 

TIOCCBRK the break bit is cleared. 

TIOCSDTR data terminal ready is set 
TIOCCDTR data terminal ready is cleared. 

TIOCGPGRP arg is the address of a word into which is placed the process group number of the control 
terminal. 

TIOCSPGRP arg is a word (typically a process id) which becomes the process group for the control 
terminal. 

FIONREAD returns in the long integer whose address is arg the number of immediately readable 
characters from the argument unit This works for files, pipes, and terminals. 

Tchars 

The second structure associated with each terminal specifies characters that are special in both the old and 
new terminal interfaces: The following structure is defined in <syslioctl.h>, which is automatically 
included in <sgtty.h> : 

struct tchars { 


char 

t_intrc; 

/* interrupt *1 

char 

t_quitc; 

1 * quit *1 

char 

t_startc; 

1 * start output *1 

char 

t_stopc; 

1 * stop output */ 

char 

t_eofc; 

1 * end-of-file *1 

char 

tjbrkc; 

1 * input delimiter (like nl) *1 


}; 

The default values for these characters are A C, A \, A Q, A S, A D, and -1. A character value of -1 eliminates 
the effect of that character. The t brkc character, by default -1, acts like a new-line in that it terminates a 
Tine,’ is echoed, and is passed to the program. The ‘stop’ and ‘start’ characters may be the same, to pro- 
duce a toggle effect. It is probably counterproductive to make other special characters (including erase and 
kill) identical. The applicable ioctl calls are: 

TIOCGETC Get the special characters and put them in the specified structure. 

TIOCSETC Set the special characters to those given in the structure. 

Local mode 

The third structure associated with each terminal is a local mode word; except for the LNOHANG bit, this 
word is interpreted only when the new driver is in use. The bits of the local mode word are: 

LCRTBS 000001 Backspace on erase rather than echoing erase 

LPRTERA 000002 Printing terminal erase mode 

LCRTERA 000004 Erase character echoes as backspace-space-backspace 
LTILDE000010 Convert ' to ' on output (for Hazeltine terminals) 

LLITOUT 000040 Suppress output translations 

LTOSTOP 000100 Send SIGTTOU for background output 
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LFLUSHO 

LNOHANG 

001000 

LCRTKIL 

LCTLECH 

LPENDIN 

LDECCTQ 

LNOFLSH 


000200 Output is being flushed 

000400 Don’t send hangup when carrier drops 

Unimplemented. 

002000 BS-space-BS erase entire line on line kill 
010000 Echo input control chars as 'X, delete as A ? 

020000 Retype pending input at next read or input character 

040000 Only A Q restarts output after "S, like DEC systems 

100000 Inhibit flushing of pending I/O when an interrupt character is typed. 


The applicable ioctl functions are: 

TIOCLBIS arg is the address of a mask which is the bits to be set in the local mode word. 

TIOCLBIC arg is the address of a mask of bits to be cleared in the local mode word. 

TIOCLSET arg is the address of a mask to be placed in the local mode word. 

TIOCLGET arg is the address of a word into which the current mask is placed. 

Local special chars 

The final structure associated with each terminal is the Uchars structure which defines interrupt characters 
for the new terminal driver. Its structure is: 


struct ltchars { 


char 

t_suspc; 

1* stop process signal *1 

char 

t_dsuspc; 

I* delayed stop process signal */ 

char 

t_rprntc; 

/* reprint line *1 

char 

t_flushc; 

1* flush output (toggles) *1 

char 

t_werasc; 

I* word erase *1 

char 

t_lnextc; 

1* literal next character *1 


}; 

The default values for these characters are A Z, A Y, A R, a O, A W, and A V. A value of -1 disables the charac- 
ter. 

The applicable ioctl functions are: 

TIOCSLTC args is the address of a ltchars structure which defines the new local special characters. 

TIOCGLTC args is the address of a ltchars structure into which is placed the current set of local special 
characters. 

FILES 

/dev/tty 

/dev/tty* 

/dev/console 

SEE ALSO 

csh(l), stty(l), ioctl(2), sigvec(2), stty(3C), getty(8), init(8) 

BUGS 

Half-duplex terminals are not supported. 

Processes that are not invoked with a control terminal, but open a dialout line can hang indefinitely. Once 
the dialout line is opened, it becomes the control terminal. Should the process then open /dev/tty, it will 
hang because /dev/tty resolves to the corresponding dialin line. The process will wait for the dialin 
sequence to complete, even though the line is already connected. 
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NAME 

udp - Internet User Datagram Protocol 
SYNOPSIS 

None; comes automatically with inet( 4F). 

DESCRIPTION 

The User Datagram Protocol (UDP) is defined to make available a datagram mode of packet switched com- 
puter communicaton in the environment of an interconnected set of computer networks. The protocol 
assumes that the Internet Protocol (IP) as described in ip(4P) is used as the underlying protocol. 

The protocol provides a procedure for application programs to send messages to other programs with a 
minimum of protocol mechanism. The protocol is transaction oriented, and delivery and duplicate protec- 
tion are not guaranteed. Applications requiring ordered reliable delivery of streams of data should use the 
Transmission Control Protocol (TCP) as described in tcp( 4P). 

The UNIX system implementation of UDP makes it available as a socket of type SOCK DGRAM. UDP 
sockets are normally used in a connectionless fashion, with the sendto and recvfrom calls described in 
send(2) and recv(2). 

A UDP socket is created with a socket (2) call: 

s = socket(AF_INET, SOCK_DGRAM, 0); 

The socket initially has no address associated with it, and may be given an address with a bind (2) call as 
described in inet (4F). If no bind call is done, then the address assignment procedure described in inet (4F) 
is repeated as each datagram is sent. 

When datagrams are sent the system encapsulates the user supplied data with UDP and IP headers. Unless 
the invoker is the super-user datagrams which would become broadcast packets on the network to which 
they are addressed are not allowed. Unless the socket has had a SODONTROUTE option enabled (see 
socket( 2)) the outgoing datagram is routed through the routing tables as described in routing (4N). If there 
is insufficient system buffer space to temporarily hold the datagram while it is being trasmitted, the sendto 
may result in a ENOBUFS error. Other errors (ENETUNREACH, EADDRNOTAVAIL, EACCES, 
EMSGSIZE) may be generated by icmp (4P) or by the network interfaces themselves, and are reflected 
back in the send call. 

As each UDP datagram arrives at a host the system strips out the IP options and checksums the data field, 
discarding the datagram if the checksum indicates that the datagram has been damaged. If no socket exists 
for the datagram to be sent to then an ICMP error is returned to the originating socket. If a socket exists for 
this datagram to be sent to, then we will append the datagram and the address from which it came to a 
queue associated with the datagram socket. This queue has limited capacity (2048 bytes of datagrams) and 
arriving datagrams which will not fit within its high-water capacity are silently discarded. 

UDP processes ICMP errors reflected to it by icmp{ 4P). QUENCH errors are ignored (this is well con- 
sidered a bug); UNREACH, TIMXCEED and PARAMPROB errors cause the socket to be disconnected 
from its peer if it was bound to a peer using bind (2) so that subsequent attempts to send datagrams via that 
socket will give an error indication. 

The UDP datagram protocol differs from IP datagrams in that it adds a checksum over the data bytes and 
contains a 16-bit socket address on each machine rather than just the 32-bit machine address; UDP 
datagrams are addressed to sockets; IP packets are addressed to hosts. 

SEE ALSO 

recv(2), send(2), inet(4F) 

“User Datagram Protocol’ ’, RFC768, John Postel, USC-ISI (Sun 800-1054-01) 

BUGS 

SIOCSHIWAT and SIOCGHIWAT ioctl’s to set and get the high water mark for the socket queue, and so 
that it can be changed from 2048 bytes to be larger or smaller, have been defined (in <sys/ioctl.h>) but not 
implemented. 
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Something sensible should be done with QUENCH errors if the socket is bound to a peer socket. 
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NAME 

. vp - Ikon 10071-5 Versatec parallel printer interface 
SYNOPSIS — SUN-2 

device vpO at inbio ? csr 0x400 priority 2 
DESCRIPTION 

This Sun interface to the Versatec printer/plotter is supported by the Ikon parallel interface board, a word 
DMA device, which is output only. 

The Versatec is normally handled by the line printer spooling system and should not be accessed by the 
user directly. 

Opening the device Idev/vpO may yield one of two errors: ENXIO indicates that the device is already in 
use; EIO indicates that the device is offline. 

The printer operates in either print or plot mode. To set the printer into plot mode you should include 
<vcmd.h> and use the ioctl(2 ) call 

ioctl(f, VSETSTATE, plotmd); 

where plotmd is defined to be 

int plotmd[] = { VPLOT, 0, 0 }; 

When going back into print mode from plot mode you normally eject paper by sending it an EOT after put- 
ting into print mode: 

int prtmd[] = { VPRINT, 0, 0 }; 

fflush(vp); 
f = fileno (vp); 

ioctl(f, VSETSTATE, prtmd); 
write(f, "\04", 1); 

FILES 

/dev/vpO 
SEE ALSO 

Multibus/Versatec Interface, Ikon Corp (Includes Versatec Manual) (Sun 800-1065-01) 

BUGS 

If you use the standard i/o library on the Versatec, be sure to explicitly set a buffer using setbuf, since the 
library will not use buffered output by default, and will run very slowly. 

Writes must start on even byte boundaries and be an even number of bytes in length. 
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NAME 

vpc - Systech VPC-2200 Versatec printer/plotter and Centronics printer interface 
SYNOPSIS — SUN-2 

device vpcO at mbio ? csr 0x480 priority 2 
device vpcl at mbio ? csr 0x500 priority 2 

DESCRIPTION 

This Sun interface to the Versatec printer/plotter and to Centronics printers is supported by the Systech 
parallel interface board, an output-only byte-wide DMA device. The device has one channel for Versatec 
devices and one channel for Centronics devices, with an optional long lines interface for Versatec devices. 

Devices attached to this interface are normally handled by the line printer spooling system and should not 
be accessed by the user directly. 

Opening the device Idev/vpO or /dev/lpO may yield one of two errors: ENXIO indicates that the device is 
already in use; EIO indicates that the device is offline. 

The Versatec printer/plotter operates in either print or plot mode. To set the printer into plot mode you 
should include <vcmd.h> and use the ioctl( 2) call: 

ioctl(f, VSETSTATE, plotmd); 

where plotmd is defined to be 

int plotmd[] = { VPLOT, 0, 0 }; 

When going back into print mode from plot mode you normally eject paper by sending it an EOT after put- 
ting into print mode: 

int prtmd[ ] = { VPRINT, 0, 0 }; 

fflush(vpc); 
f = fileno(vpc); 
iocd(f, VSETSTATE, prtmd); 
write(f, "\04", 1); 

FILES 

/dev/vpO 

/dev/lpO 

SEE ALSO 

Systech VPC-2200 Versatec Printer/Plotter Controller Technical Manual 

BUGS 

If you use the standard I/O libraiy on the Versatec, be sure to explicitly set a buffer using setbuf, since the 
library will not use buffered output by default, and will run very slowly. 


350 


Last change: 16 September 1985 


Sun Release 3.0 



WIN (4S) 


SPECIAL FILES 


WIN (4S) 


NAME 

win - Sun window system 
SYNOPSIS 

pseudo-device win number 
pseudo-device Ato\>number 

DESCRIPTION 

The win pseudo-device accesses the system drivers supporting the Sun window system, number, in the 
device description line above, indicates the maximum number of windows supported by the system. 
number is set to 128 in the GENERIC system configuration file used to generate the kernel used in Sun sys- 
tems as they are shipped. The dtop pseudo-device line indicates the number of separate “desktops” 
(frame buffers) that can be actively running the Sun window system at once. In the GENERIC file, this 
number is set to 4. 

Each window in the system is represented by a Idev/win* device. The windows are organized as a tree 
with windows being subwindows of their parents, and covering/covered by their siblings. Each window 
has a position in the tree, a position on a display screen, an input queue, and information telling what parts 
of it are exposed. 

The window driver multiplexes keyboard and mouse input among the several windows, tracks the mouse 
with a cursor on the screen, provides each window access to information about what parts of it are exposed, 
and notifies the manager process for a window when the exposed area of the window changes so that the 
window may repair its display. 

Full information on the window system functions is given in the Programmer’ s Reference Manual for 
SunWindows. 

FILES 

/dev/win[0-9] 

/dev/win[0-9][0-9] 

SEE ALSO 

Programmer’ s Reference Manual for SunWindows 
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NAME 

xt - Xylogics 472 1/2 inch tape controller 
SYNOPSIS — SUN-3 

controller xtcO at vmel6dl6 ? csr 0xee60 priority 3 vector xtintr 100 
controller xtcl at vmel6dl6 ? csr 0xee68 priority 3 vector xtintr 101 
tape xtO at xtcO drive 0 flags 1 
tape xtl at xtcl drive 0 flags 1 

SYNOPSIS — SUN-2 

controller xtcO at mbio ? csr 0xee60 priority 3 

controller xtcO at vmel6 ? csr 0xee60 priority 3 vector xtintr 100 

controller xtcl at mbio ? csr 0xee68 priority 3 

controller xtcl at vmel6 ? csr 0xee68 priority 3 vector xtintr 101 

tape xtO at xtcO drive 0 flags 1 

tape xtl at xtcl drive 0 flags 1 

DESCRIPTION 

The Xylogics 472 tape controller controls Pertec-interface 1/2" tape drives such as the CDC Keystone III, 
providing a standard tape interface to the device, see mtio(4). This controller is used to support high speed 
or high density drives, which are not supported effectively by the older TapeMaster controller (tm(4)). 

The flags field is used to control remote density select operation: a 0 specifies no remote density selection is 
to be attempted, a 1 specifies that the Pertec density-select line is used to toggle between high and low den- 
sity; a 2 specifies that the Perte speed-select line is used to toggle between high and low density. The 
default is 1, which is appropriate for the CDC Keystone III (92185) and the Telex 9250. In no case will the 
controller select among more than 2 densities. 

SEE ALSO 

tar(l), tm(4), mtio (4) 
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NAME 

xy - Disk driver for Xylogics SMD Disk Controllers 
SYNOPSIS — SUN-3 

controller xycO at vmel6dl6 ? csr 0xee40 priority 2 vector xyintr 72 

controller xycl at vmel6dl6 ? csr 0xee48 priority 2 vector xyintr 73 

disk xyO at xycO drive 0 

disk xyl at xycO drive 1 

disk xy2 at xycl drive 0 

disk xy3 at xycl drive 1 

The two controller lines given in the synopsis sections above specify the first and second Xylogics 450 
SMD disk controller in a Sun system. 

SYNOPSIS — SUN-2 

controller xycO at vmel6 ? csr 0xee40 priority 2 vector xyintr 72 

controller xycl at vmel6 ? csr 0xee48 priority 2 vector xyintr 73 

controller xycO at mbio ? csr 0xee40 priority 2 

controller xycl at mbio ? csr 0xee48 priority 2 

disk xyO at xycO drive 0 

disk xyl at xycO drive 1 

disk xy2 at xycl drive 0 

disk xy3 at xycl drive 1 

The first two controller lines specify the first and second Xylogics 450 SMD disk controllers in a Sun- 
2/160 VMEbus based system. The third, and fourth controller lines specify the first and second Xylogics 
450 SMD disk controllers in a Sun-2/120 or a SUn-2/170 Multibus based system. 

DESCRIPTION 

Files with minor device numbers 0 through 7 refer to various portions of drive 0; minor devices 8 through 
15 refer to drive 1, and so on. The standard device names begin with ‘xy’ followed by the drive number 
and then a letter a-h for partitions 0-7 respectively. The character ? stands here for a drive number in the 
range 0-7. 

The block files access the disk via the system’s normal buffering mechanism and may be read and written 
without regard to physical disk records. There is also a ‘raw’ interface which provides for direct transmis- 
sion between the disk and the user’s read or write buffer. A single read or write call usually results in only 
one I/O operation; therefore raw I/O is considerably more efficient when many words are transmitted. The 
names of the raw files conventionally begin with an extra ‘r.’ 

In raw I/O counts should be a multiple of 512 bytes (a disk sector). Likewise seek calls should specify a 
multiple of 512 bytes. 

DISK SUPPORT 

This driver handles all SMD drives by reading a label from sector 0 of the drive which describes the disk 
geometry and partitioning. 

The xy?a partition is normally used for the root file system on a disk, the xy?b partition as a paging area, 
and the xy?c partition for pack-pack copying (it normally maps the entire disk). The rest of the disk is nor- 
mally the xy?g partition. 

FILES 

/dev/xy[0-7][a-h] block files 

/dev/rxy[0-7][a-h] raw files 

SEE ALSO 

dkio(4S) 

Xylogics Model 450 Peripheral Processor SMD Disk Subsystem Maintenance and Reference Manual (Sun 
800-1025-01) 
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DIAGNOSTICS 

xyc%d: self test error %x - %s. Self test error in controller, see the Maintenance and Reference Manual. 

xyc%d: address mode jumper is wrong. The controller is strapped for 24-bit Multibus addresses. Sun 
systems use 20-bit addresses for Multibus based systems and 24-bit addresses for VMEbus based systems. 
See the subsection on the Xylogics controller in the appropriate Sun Hardware Installation Manual for 
your machine(s) for instructions on how to set the jumpers on the 450. 

xyattach: can’t get bad sector info. The bad sector forwarding information for the disk, which is kept on 
the last cylinder, could not be read. 

xy%d: drive type %d clash with xy%d. The 450 does not support mixing the drive types found on these 
units on a single controller. 

xy%d: initialization failed. 

xy %d: error %\ reading label on head %d. Error reading drive geometry/partition table information. 
xy%d: Corrupt label. The geometry/partition label checksum was incorrect. 
xy%d: Unsupported phys partition# %d. 
xy%d: offline. 

xy%d%c: cmd how (msg) blk %d. A command such as read, write, or format encountered a error condi- 
tion (how): either it failed, the unit was restored, or an operation was retry’ ed. The msg is derived from the 
error number given by the controller, indicating a condition such as ‘drive not ready’, ‘sector not found’ or 
‘disk write protected’. 

BUGS 

In raw I/O read and write (2) truncate file offsets to 512-byte block boundaries, and write scribbles on the 
tail of incomplete blocks. Thus, in programs that are likely to access raw devices, read, write and lseek(2) 
should always deal in 512-byte multiples. 
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NAME 

zs - zilog 8530 SCC serial comunications driver 
SYNOPSIS — SUN-3 

device zsO at obio ? csr 0x20000 flags 3 priority 3 
device zsl at obio ? csr 0x00000 flags 0x103 priority 3 

SYNOPSIS — SUN-2 

device zsO at virtual ? csr 0xeec800 flags 3 priority 3 
device zsl at virtual ? csr OxeecOOO flags 0x103 priority 3 
device zs2 at mbmem ? csr 0x80800 flags 3 priority 3 
device zs3 at mbmem ? csr 0x81000 flags 3 priority 3 
device zs4 at mbmem ? csr 0x84800 flags 3 priority 3 
device zs5 at mbmem ? csr 0x85000 flags 3 priority 3 

DESCRIPTION 

The Zilog 8530 provides 2 serial communication lines with full modem control. Each line behaves as 
described in tty( 4). Input and output for each line may independendy be set to run at any of 16 speeds; see 
try (4) for the encoding. 

Of the synopsis lines above, the line for zsO specifies the serial I/O ports provided by the CPU board, the 
line for zsl specifies the Video Board ports (which are used for keyboard and mouse), the lines for zs2 and 
zs3 specify the first and second ports on the first SCSI board in a system, and those for zs4 and zs5 specify 
the first and second ports provided by the second SCSI board in a system, respectively. 

Bit i of flags may be specified to say that a line is not properly connected, and that the line i should be 
treated as hard-wired with carrier always present. Thus specifying “flags 0x2” in the specification of zsO 
would cause line ttyb to be treated in this way. 

To allow a single tty line to be connected to a modem and used for both incoming and outgoing calls, a 
special feature, controlled by the minor device number, has been added. Minor device numbers in the 
range 0 - 127 correspond directly to the normal tty lines and are named tty*. Minor device numbers in the 
range 128 - 256 correspond to the same physical lines as those above (i.e. the same line as the minor dev- 
ice number minus 128) and are (conventionally) named cua*. The cua lines are special in that they can be 
opened even when there is no carrier on the line. Once a cua line is opened, the corresponding tty line can 
not be opened until the cua line is closed. Also, if the tty line has been opened successfully (usually only 
when carrier is recognized on the modem) the corresponding cua line can not be opened. This allows a 
modem to be attached to Idevlttya (usually renamed to IdevIttydO ) and used for dialin (by enabling the line 
for login in /etc/ttys) and also used for dialout (by tip( 1C) or uucp( 1C)) as Idev/cuaO when no one is logged 
in on the line. Note that the bit in the flags word in the config file (see above) must be zero for this line. 

FILES 

/dev/tty[a, b, s0-s3] 

/dev/ttyd[0-9, a-f] 

/dev/cua[0-9, a-f] 

SEE ALSO 

tty(4) 

Zilog Z8030/Z8530 SCC Serial Communications Controller (Sun 800-1052-01) 

DIAGNOSTICS 

zs%d%c: silo overflow. The character input silo overflowed before it could be serviced. 
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NAME 

a.out - assembler and link editor output 

SYNOPSIS 

#include <a.out.h> 

#include <stab.h> 

#include <nlist.h> 

DESCRIPTION 

A.out is the output file of the assembler as( 1) and the link editor M( 1). The link editor makes a.out execut- 
able if there were no errors and no unresolved external references. Layout information as given in the 
include file for the Sun system is: 

/* 

* Header prepended to each a.out file. 

*1 

struct exec { 



unsigned 

short 

ajnachtype; 

/* machine type */ 


unsigned 

short 

amagic; 

/* magic number */ 


unsigned 


atext; 

/* size of text segment */ 


unsigned 


a_data; 

/* size of initialized data */ 


unsigned 


a_bss; 

/* size of uninitialized data */ 


unsigned 


a_syms; 

/* size of symbol table */ 


unsigned 


aentry; 

/* entry point */ 


unsigned 


atrsize; 

/* size of text relocation *1 

}; 

unsigned 


adrsize; 

1* size of data relocation */ 

#define 

M 68010 

1 


/* runs on either 68010 or 68020 */ 

#define 

M_68020 

2 


/* runs only on 68020 */ 

#define 

OMAGIC 

0407 


/* magic number for old impure format */ 

#define 

NMAGIC 

0410 


/* magic number for read-only text */ 

#define 

ZMAGIC 

0413 


/* magic number for demand load format */ 

#define 

PAGSIZ 

0x2000 


/* page size - same for sun-2 and sun-3 */ 

#define 

SEGSIZ 

0x20000 


/* segment size - same for sun-2 and sun-3 * 


/* 

* The following macros take exec structures as arguments. N_BADMAG(x) returns 

* 0 if the file has a reasonable magic number. 

*/ 

#define N_BADMAG(x) \ 

(((x).a_magic)!=OMAGIC && ((x).a_magic)!=NMAGIC && ((x).a_magic)!=ZMAGIC) 


/* 

* Offsets to text | symbols | strings. 

*/ 

#define N_TXTOFF(x) \ 

((x).a_magic==ZMAGIC ? 0 : sizeof (struct exec)) 

#define N_SYMOFF(x) \ 

(N_TXTOFF(x) + (x).a_text+(x).a_data + (x).a_trsize+(x).a_drsize) 
#define N_STROFF(x)\ 

(N_SYMOFF(x) + (x).a_syms) 

I* 
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* Macros which take exec structures as arguments and tell where the 

* various pieces will be loaded. 

*/ 

#define N_TXTADDR(x) PAGSIZ 

#define N_D AT ADDR(x) \ 

(((x).a_magic==OMAGIC)? (N_TXTADDR(x)+(x).a_text) \ 

: (SEGSIZ+((N_TXTADDR(x)+(x).a_text-l) & '(SEGSIZ-1)))) 

#define N_BSSADDR(x) (N_DATADDR(x)+(x).a_data) 

The a. out file has five sections: a header, the program text and data, relocation information, a symbol table 
and a string table (in that order). In the header the sizes of each section are given in bytes. The last three 
sections may be absent if the program was loaded with the ‘-s’ option of Id or if the symbols and relocation 
have been removed by strip (l). 

The machine type in the header indicates the type of hardware on which the object code may be executed. 
Sun-2 code may be executed on Sun-3 systems, but not vice versa. Program files predating release 3.0 are 
recognized by a machine type of 0. 

If the magic number in the header is OMAGIC (0407), it means that this is a non-sharable text which is not 
to be write-protected, so the data segment is immediately contiguous with the text segment. This is rarely 
used. If the magic number is NMAGIC (0410) or ZMAGIC (0413), the data segment begins at the first seg- 
ment boundary following the text segment, and the text segment is not writable by the program; other 
processes executing the same file will share the text segment. For ZMAGIC format, the text and data sizes 
must both be multiples of the page size, and the pages of the file will be brought into the running image as 
needed, and not pre-loaded as with the other formats. This is suitable for large programs and is the default 
format produced by ld( 1). The macros N TXTADDR, N DATADDR, and N BSSADDR give the memory 
addresses at which the text, data, and bss segments, respectively, will be loaded. 

In the ZMAGIC format, the size of the header is included in the size of the text section; in other formats, it 
is not 

When an a. out file is executed, three logical segments are set up: the text segment, the data segment (with 
uninitialized data, which starts off as all 0, following initialized data), and a stack. For the ZMAGIC format, 
the header is loaded with the text segment; for other formats it is not. 

Program execution begins at the address given by the value of the a-entry field. In all file types other than 
XMAGIC, the is the same as N_TXTADDR(x). In ZMAGIC files it is N_TXTADDR + sizeof(struct 
exec). 

The stack starts at the highest possible location in the memory image, and grows downwards. The stack is 
automatically extended as required. The data segment is extended as requested by brk( 2) or sbrk( 2). 

After the header in the file follow the text, data, text relocation data relocation, symbol table and string 
table in that order. The text begins at the beginning of the file for ZMAGIC format or just after the header 
for the other formats. The N_TXTOFF macro returns this absolute file position when given the name of an 
exec structure as argument. The data segment is contiguous with the text and immediately followed by the 
text relocation and then the data relocation information. The symbol table follows all this; its position is 
computed by the N_SYMOFF macro. Finally, the string table immediately follows the symbol table at a 
position which can be gotten easily using N_STROFF. The first 4 bytes of the string table are not used for 
string storage, but rather contain the size of the string table; this size includes the 4 bytes; thus, the 
minimum string table size is 4. 

RELOCATION 

The value of a byte in the text or data which is not a portion of a reference to an undefined external symbol 
is exactly that value which will appear in memory when the file is executed. If a byte in the text or data 
involves a reference to an undefined external symbol, as indicated by the relocation information, then the 
value stored in the file is an offset from the associated external symbol. When the file is processed by the 


358 


Last change: 21 December 1985 


Sun Release 3.0 



A.OUT ( 5 ) 


FILE FORMATS 


A.OUT ( 5 ) 


link editor and the external symbol becomes defined, the value of the symbol is added to the bytes in the 
file. 

If relocation information is present, it amounts to eight bytes per relocatable datum as in the following 
structure: 

/* 

* Format of a relocation datum. 

*/ 

struct relocation_info { 

int r_address; /* address which is relocated */ 

unsigned r_symbolnum:24,/* local symbol ordinal */ 

r_pcrel: 1, /* was relocated pc relative already */ 

r_length:2, /* 0=byte, l=word, 2=long */ 

rexterml, /* does not include value of sym referenced */ 

:4; /* nothing, yet */ 

}; 

There is no relocation information if a_trsize+a_drsize==0. If r extem is 0, then r symbolnum is actually 
a n type for the relocation (that is, N TEXT meaning relative to segment text origin.) 

SYMBOL TABLE 

The layout of a symbol table entry and the principal flag values that distinguish symbol types are given in 
the include file as follows: 

/* 

* Format of a symbol table entry. 

*/ 

struct nlist { 



union { 

char 

*n_name; 

/* for use when in-memory */ 



long 

n_strx; 

/* index into file string table */ 


} n_un; 
unsigned char 

n _type; 


/* type flag, that is, N_TEXT etc; see below */ 


char 

nother; 




short 

n_desc; 


/* see <stab.h> */ 

1 . 

unsigned 

n_value; 


/* value of this symbol (or adb offset) */ 

J » 

#define 

nhash 

n_desc 


1 * used internally by Id */ 

/* 





* Simple values for n_type. 




*1 

#define 

N UNDF 

0x0 


1 * undefined */ 

#define 

N ABS 

0x2 


/* absolute */ 

#define 

N TEXT 

0x4 


/* text */ 

#define 

N DATA 

0x6 


/* data */ 

#define 

N BSS 

0x8 


/* bss */ 

#define 

N COMM 

0x12 


/* common (internal to Id) */ 

#define 

N_FN 

Oxlf 


/* file name symbol */ 

#define 

N EXT 

01 


/* external bit, or’ed in */ 

#define 

N TYPE 

Oxle 


1 * mask for all the type bits */ 


/* 

* Other permanent symbol table entries have some of the N_STAB bits set. 
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* These are given in <stab.h> 

*/ 

#define N_STAB OxeO /* if any of these bits set, don’t discard *1 

In the a.out file a symbol’s nun.nstrx field gives an index into the string table. A n strx value of 0 indi- 
cates that no name is associated with a particular symbol table entry. The field n_un.n_name can be used 
to refer to the symbol name only if the program sets this up using n_strx and appropriate data from the 
string table. Because of the union in the nlist declaration, it is impossible in C to statically initialize such a 
structure. If this must be done (as when using nlist(h )) the file <nlist.h> should be included, rather that 
<a.out.h>; this contains the declaration without the union. 

If a symbol’s type is undefined external, and the value field is non-zero, the symbol is interpreted by the 
loader Id as the name of a common region whose size is indicated by the value of the symbol. 

SEE ALSO 

adb(l), as(l), cc(l), dbx(l), ld(l), nm(l), pc(l), strip(l) 
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NAME 

aliases - aliases file for sendmail 

SYNOPSIS 

/usr/lib/aliases 

/usr/Iib/aliases.dir 

/usr/lib/aliases.pag 

DESCRIPTION 

These files describe user id aliases used by lusrllibtsendma.il. lusr/libl aliases is formatted as a series of 
lines of the form 

name: namel, name2, name_3, . . . 

The name is the name to alias, and the namen are the aliases for that name. Lines beginning with white 
space are continuation lines. Lines beginning with ‘ # ’ are comments. 

Aliasing occurs only on local names. Loops can not occur, since no message will be sent to any person 
more than once. 

After aliasing has been done, local and valid recipients who have a “.forward’ ’ file in their home directory 
have messages forwarded to the list of users defined in that file. 

lusrllibl aliases is only the raw data file; the actual aliasing information is placed into a binary format in the 
files lusr/lib/aliases.dir and lusrllibl aliases. pag using the program newaliases( 8). A newaliases command 
should be executed each time that lusrllibl aliases is changed for the change to take effect. 

Several kinds of name’s are special: 

owner-mary: fred 

any errors resulting from a mail to mary are directed to fred instead of back to the person who sent 
the message. This is most useful when mary is a mailing list rather than an individual. 

beer: :include:/usr/cyndi/beer; 

All colons and semicolons are required as shown. The list of names in lusr/cyndilbeer is included 
in the name n list for the beer alias, in addition to any other names in the nameji list. This 
mechanism is for setting up a mailing list so that lusrlliblaliases doesn’t have to be changed when 
people are added to or removed from the list. The included file (that is, lusrlcyndi/beer in this 
case) may be changed at any time, and changes take effect immediately. 

SEE ALSO 

newaliases(8), dbm(3X), sendmail(8) 

SENDMAIL Installation and Operation Guide. 

SENDMAIL An Internetwork Mail Router. 

BUGS 

Because of restrictions in dbm{ 3X) a single alias cannot contain more than about 1000 bytes of informa- 
tion. You can get longer aliases by “chaining”; that is, make the last name in the alias be a dummy name 
which is a continuation alias. 
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NAME 

ar - archive (library) file format 

SYNOPSIS 

#indude <ar.h> 

DESCRIPTION 

The archive command ar combines several files into one. Archives are used mainly as libraries to be 
searched by the link-editor Id. 

A file produced by ar has a magic string at the start, followed by the constituent files, each preceded by a 
file header. The magic number and header layout as described in the include file are: 

/* @(#)ar.h 1.2 84/12/22 SMI; from UCB 4. 1 83/05/03*/ 

#defineARMAG "!<arch>\n" 

#define SARMAG 8 

#define ARFMAG "V 

struct arhdr { 

char ar_name[16]; 
char ar_date[12]; 
char ar_uid[6]; 
char ar_gid[6]; 
char ar_mode[8]; 
char ar_size[10]; 
char ar_fmag[2]; 

}; 

The name is a blank-padded string. The ar Jmag field contains ARFMAG to help verify the presence of a 
header. The other fields are left-adjusted, blank-padded numbers. They are decimal except for arjnode, 
which is octal. The date is the modification date of the file at the time of its insertion into the archive. 

Each file begins on a even (0 mod 2) boundary; a new-line is inserted between files if necessary. Neverthe- 
less the size given reflects the actual size of the file exclusive of padding. 

There is no provision for empty areas in an archive file. 

The encoding of the header is portable across machines. If an archive contains printable files, the archive 
itself is printable. 

SEE ALSO 

ar(l), ld(l), nm(l) 

BUGS 

File names lose trailing blanks. Most software dealing with archives takes even an included blank as a 
name terminator. 
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NAME 

core - format of memory image file 
SYNOPSIS 

#include <sys/core.h> 

DESCRIPTION 

The UNIX System writes out a memory image of a terminated process when any of various errors occur. 
See sigvec (2) for the list of reasons; the most common are memory violations, illegal instructions, bus 
errors, and user-generated quit signals. The memory image is called ‘core’ and is written in the process’s 
working directory (provided it can be; normal access controls apply). 

The maximum size of a core file is limited by setrlimit{ 2). Files which would be larger than the limit are 
not created. 

Set-user-id programs do not produce core files when they terminate as this would be a security loophole. 

The core file consists of a core structure defined in the <syslcore.h> file. The core structure includes the 
registers, the floating point status, the program’s header, the size of the text, data, and stack segments, the 
name of the program and the number of the signal that terminated the process. The program’s header is 
described by the exec structure defined in the <syslexec.h> file. 

The remainder of the core file consists first of the data pages and then the stack pages of the process image. 
The amount of data space image in the core file is given (in bytes) by the c dsize member of the core struc- 
ture. The amount of stack image in the core file is given (in bytes) by the c_ssize member of the core 
structure. 

SEE ALSO 

adb(l), dbx(l), sigvec(2), setrlimit(2) 
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NAME 

cpio - format of cpio archive 
DESCRIPTION 

The old format header structure, when the c option is not used, is: 
struct { 

short hmagic, 
hdev, 
hino, 
hmode, 
huid, 
hgid, 
hnlink, 
hrdev, 
h_mtime[2], 
hnamesize, 
h_filesize[2]; 

char h_name[h_namesize rounded to a word] ; 

} Hdr; 

but note that the byte order here is that of the PDP-11 and the VAX, and that for the Sun you have to use 
swab (3) after reading and before writing headers. 

When the c option is used, the header information is described by the statement below: 

sscanf(Chdr, "%6o%6o%6o%6o%6o%6o%6o%6o%lllo%6o%6o%s", 

&Hdr.h_magic, &Hdr.h_dev, &Hdr.h_ino, &Hdr.h_mode, 

&Hdr.h_uid, &Hdr.h_gid, &Hdr.h_nlink, &Hdr.h_rdev, 

&Hdr.h_mtime, &Hdr.h_namesize, &Hdr.h_filesize, &Hdr.h_name); 

Longtime and Longfile are equivalent to Hdr.hjntime and Hdr.h Jilesize, respectively. The contents of 
each file is recorded in an element of the array of varying length structures, archive, together with other 
items describing the file. Every instance of h magic contains the constant 070707 (octal). The items 
h dev through hjntime have meanings explained in stat{2). The length of the null-terminated path name 
h name, including the null byte, is given by h namesize. 

The last record of the archive always contains the name TRAILER!!!. Special files, directories, and the 
trailer, are recorded with h Jilesize equal to zero. 

SEE ALSO 

cpio(l), find(l), stat(2) 
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NAME 

crontab - table of times to ran periodic jobs 

SYNOPSIS 

/usr/lib/crontab 

DESCRIPTION 

The letclcron utility is a permanent process, started by /etc/rc. local, that wakes up once every minute. 
/etc/ cron consults the file /usr/lib/crontab to find out what tasks are to be done, and at what time. 

Each line in I usr/lib/crontab consists of six fields, separated by spaces or tabs, as follows: 

1 . minutes field, which can have values in the range 0 through 59. 

2. hours field, which can have values in the range 0 through 23. 

3. day of the month, in the range 1 through 31. 

4. month of the year, in the range 1 through 12. 

5. day of the week, in the range 1 through 7. Monday is day 1 in this scheme of things. 

6. (the remainder of the line ) is the command to be run. A percent character in this field is 
translated to a new-line character. Only the first line (up to a % or end of line) of the command 
field is executed by the Shell. The other lines are made available to the command as standard 
input. 

Any of fields 1 through 5 can be a list of values separated by commas. A field can be a pair of numbers 
separated by a hyphen, indicating that the job is to be done for all the times in the specified range. If a field 
is an asterisk character (*) it means that the job is done for all possible values of the field. 

FILES 

/usr/lib/crontab 

SEE ALSO 

cron(8), rc(8) 

EXAMPLE 

0 0 * * * calendar - 

15 0 * * * /etc/sa -s >/dev/null 

15 4 * * * find /usr/preserve -mtime +7 -a -exec rm -f {} ; 

40 4 * * * find / -name ’#*’ -atime +3 -exec rm -f {} ; 

0,15,30,45 * * * * /etc/atrun 

0,10,20,30,40,50 * * * * /etc/dmesg - »/usr/adm/messages 
5 4 * * * sh /etc/newsyslog 

The calendar command run at minute 0 of hour 0 (midnight) of every day. The /etc/sa command runs at 
15 minutes after midnight every day. The two find commands ran at 15 minutes past four and at 40 
minutes past four, respectively, every day of the year. The atrun command (which processes shell scripts 
users have set up with at) runs every 15 minutes. The /etc/dmesg command appends kernel messages to 
the lusr/adm/messages file every ten minutes, and finally, the lusr/adm/syslog script runs at five minutes 
after four every day. 
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NAME 

dir - format of directories 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/dir.h> 

DESCRIPTION 

A directory behaves exactly like an ordinary file, save that no user may write into a directory. The fact that 
a file is a directory is indicated by a bit in the flag word of its i-node entry; see/s(5). The structure of a 
directory entry as given in the include file is: 

I* 

* A directory consists of some number of blocks of DIRBLKSIZ 

* bytes, where DIRBLKSIZ is chosen such that it can be transferred 

* to disk in a single atomic operation (e.g. 512 bytes on most machines). 

* 

* Each DIRBLKSIZ byte block contains some number of directory entry 

* structures, which are of variable length. Each directory entry has 

* a struct direct at the front of it, containing its inode number, 

* the length of the entry, and the length of the name contained in 

* the entry. These are followed by the name padded to a 4 byte boundary 

* with null bytes. All names are guaranteed null terminated. 

* The maximum length of a name in a directory is MAXNAMLEN. 

* 

* The macro DIRSIZ(dp) gives the amount of space required to represent 

* a directory entry. Free space in a directory is represented by 

* entries which have dp->d_reclen > DIRSIZ(dp). All DIRBLKSIZ bytes 

* in a directory block are claimed by the directory entries. This 

* usually results in the last entry in a directory having a large 

* dp->d_reclen. When entries are deleted from a directory, the 

* space is returned to the previous entry in the same directory 

* block by increasing its dp->d_reclen. If the first entry of 

* a directory block is free, then its dp->d_ino is set to 0. 

* Entries other than the first in a directory do not normally have 

* dp->d_ino set to 0. 

*1 

#ifdef KERNEL 

#define DIRBLKSIZ DEVBSIZE 
#else 

#define DIRBLKSIZ 512 
#endif 

#define MAXNAMLEN 255 
/* 

* The DIRSIZ macro gives the minimum record length which will hold 

* the directory entry. This requires the amount of space in struct direct 

* without the d name field, plus enough space for the name with a terminating 

* null byte (dp->d_namlen+l), rounded up to a 4 byte boundary. 

*/ 

#undef DIRSIZ 

#define DIRSIZ(dp) ((sizeof (struct direct) - (MAXNAMLEN+1)) + (((dp)->d_namlen+l + 3) &' 3)) 
struct direct { 
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u_long dino; 

short dreclen; 

short dnamlen; 

char d_name[MAXNAMLEN + 1]; 

/* typically shorter */ 

}; 

struct dirdesc { 

int ddfd; 

long ddloc; 

long ddsize; 

char dd_buf[DIRBLKSIZ]; 

}; 

By convention, the first two entries in each directory are for V and The first is an entry for the direc- 
tory itself. The second is for the parent directory. The meaning of is modified for the root directory of 
the master file system (“/”), where has the same meaning as V. 

SEE ALSO 

fs(5), readdir(3) 
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NAME 

dump, dumpdates - incremental dump format 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/inode.h> 

#include <dumprestor.h> 


DESCRIPTION 

Tapes used by dump and restore^) contain: 


a header record 

two groups of bit map records 

a group of records describing directories 

a group of records describing files 

The format of the header record and of the first record of each description as given in the include file 
<dumprestor.h> is: 


#define NTREC 

10 

#define MLEN 16 
#define MSEZ 4096 

#define TS TAPE 

1 

#define TS INODE 

2 

#define TS BITS 

3 

#define TS ADDR 

4 

#define TS END 

5 

#define TS CLRI 

6 

#define MAGIC 

(int) 60011 

#define CHECKSUM 

(int) 84446 

struct spcl { 

int 

ctype; 

timet 

cdate; 

timet 

cddate; 

int 

cvolume; 

daddr t 

ctapea; 

inot 

cinumber; 

int 

cmagic; 

int 

cchecksum; 

struct 

dinode 

int 

c count; 

char 

c_addr[BSIZE]; 

} spcl; 

struct idates { 

char 

id_name[16]; 

char 

idincno; 

timet 

idddate; 


}; 


c_dinode; 


#define DUMPOUTFMT"%-16s %c %s" /* for printf */ 

/* name, incno, ctime(date) *1 

#define DUMPINFMT "%16s %c %r\n]\n" /* inverse for scanf */ 
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NTREC is the default number of 1024 byte records in a physical tape block, changeable by the b option to 
dump. MLEN is the number of bits in a bit map word. MSIZ is the number of bit map words. 

The TS_ entries are used in the cjype field to indicate what sort of header this is. The types and then- 
meanings are as follows: 

TS_TAPE Tape volume label 

TS INODE A file or directory follows. The c dinode field is a copy of the disk inode and contains bits 
telling what sort of file this is. 

TS BITS A bit map follows. This bit map has a one bit for each inode that was dumped. 

TSADDR A subrecord of a file description. See caddr below. 

TSEND End of tape record. 

TS CLRI A bit map follows. This bit map contains a zero bit for all inodes that were empty on the 
file system when dumped. 

MAGIC All header records have this number in cjnagic. 

CHECKSUM Header records checksum to this value. 

The fields of the header structure are as follows: 

c type The type of the header. 

c date The date the dump was taken. 

c ddate The date the file system was dumped from. 

c volume The current volume number of the dump. 

c tapea The current number of this (1024-byte) record. 

c inumber The number of the inode being dumped if this is of type TS INODE. 

cjnagic This contains the value MAGIC above, truncated as needed. 

c checksum This contains whatever value is needed to make the record sum to CHECKSUM. 

c dinode This is a copy of the inode as it appears on the file system; see/r(5). 

c count The count of characters in c addr. 

c addr An array of characters describing the blocks of the dumped file. A character is zero if the 

block associated with that character was not present on the file system, otherwise the char- 
acter is non-zero. If the block was not present on the file system, no block was dumped; 
the block will be restored as a hole in the file. If there is not sufficient space in this record 
to describe all of the blocks in a file, TS ADDR records will be scattered through the file, 
each one picking up where the last left off. 

Each volume except the last ends with a tapemark (read as an end of file). The last volume ends with a 
TS END record and then the tapemark. 

The structure i dates describes an entry in the file letcldumpdates where dump history is kept. The fields of 
the structure are: 

id name The dumped filesystem is ‘/d svlidjiam’ . 

id incno The level number of the dump tape; see dump( 8). 

id ddate The date of the incremental dump in system format see types(5). 

FILES 

/etc/dumpdates 
SEE ALSO 

dump(8), restore(8), fs(5), types(5) 

BUGS 

Should more explicitly describe format of dumpdates file. 
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NAME 

environ - user environment 


SYNOPSIS 

extern char **environ; 

DESCRIPTION 

An array of strings called the ‘environment’ is made available by execve(2) when a process begins. By 
convention these strings have the form ‘name=value’ . The following names are used by various com- 
mands: 


The sequence of directory prefixes that sh, time, nice(l), etc., apply in searching for a file 
known by an incomplete path name. The prefixes are separated by The login(l) process 
sets PATH=:/usr/ucb:/bin:/usr/bin. 


HOME 

TERM 


A user’s login directory, set by login( 1) from the password file passwd{5). 

The kind of terminal for which output is to be prepared. This information is used by com- 
mands, such as nroff or plot( 1G), which may exploit special terminal capabilities. See 
letc/termcap ( termcap {5 )) for a list of terminal types. 


SHELL The file name of the user’s login shell. 
TERMCAP 


The string describing the terminal in TERM, or the name of the termcap file, see 
termcap(i),termcap(5), 

EXINIT A startup list of commands read by ex(l), edit(l), and vi'(l). 

USER The login name of the user. 


Further names may be placed in the environment by the export command and ‘name=value’ arguments in 
sh{\), or by the setenv command if you use csh( 1). Arguments may also be placed in the environment at 
the point of an execve(2). It is unwise to conflict with certain sh(l) variables that are frequently exported 
by ‘.profile’ files: MAIL, PS1, PS2, IFS. 

SEE ALSO 

csh(l), ex(l), login(l), sh(l), getenv(3), execve(2), system(3), termcap(3X), termcap(5) 
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NAME 

ethers - ethemet address to hostname database 
DESCRIPTION 

The ethers file contains information regarding the known (48 bit) ethemet addresses of hosts on the inter- 
net. For each host on an ethemet, a single line should be present with the following information: 

ethemet address 
official host name 

Items are separated by any number of blanks and/or tabs. A ‘#’ indicates the beginning of a comment 
extending to the end of line. 

The standard form for ethemet addresses is “x:x:x:x:x:x” where x is a hexadecimal number between 0 and 
ff, representing one byte. The address bytes are always in network order. Host names may contain any 
printable character other than a space, tab, newline, or comment character. It is intended that host names in 
the ethers file correspond to the host names in the hosts( 5) file. 

The ether line () routine from the ethemet address manipulation library, ethers (iN) may be used to scan 
lines of the ethers file. 

FILES 

/etc/ethers 

SEE ALSO 

ethers(3N), hosts(5) 
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NAME 

exports - NFS file systems being exported 
SYNOPSIS 

/etc/exports 


DESCRIPTION 

The file letclexports describes the file systems which are being exported to nfs(4) clients. It is created by 
the system administrator using a text editor and processed by the mount request daemon mountd(%c ) each 
time a mount request is received. 


The file consists of a list of file systems and the net groups (5) or machine names allowed to remote mount 
each file system. The file system names are left justified and followed by a fist of names separated by 
white space. The names will be looked up in I etc! net groups and then in I etc! hosts. A file system name 
with no name fist following means export to everyone. A “#” anywhere in the file indicates a comment 
extending to the end of the line it appears on. Lines beginning with white space are continuation lines. 

EXAMPLE 


/usr clients 

/usr/local 

/usr2 phoenix sun sundae 

FILES 


# export 

# export 

# export 


to my clients 

to the world 

to only these machines 


/etc/exports 


SEE ALSO 

mountd(8c), nfs(4) 
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NAME 

fcntl - file control options 

SYNOPSIS 

#include <fcntl.h> 

DESCRIPTION 

The fcntl {2) function provides for control over open files. This include file describes requests and argu- 
ments to fcntl and open (2) as shown below: 

/* @(#)fcntl.h 1.2 83/12/08 SMI; from UCB 4.2 83/09/25 */ 


/* 


* Flag values accessible to open(2) and fcnd(2) 

* (The first three can only be set by open) 

*/ 


#define ORDONLY 0 

#define O WRONLY 1 

#define O RDWR 2 

#define ONDELAY FNDELAY 

#define O APPEND F APPEND 


/* Non-blocking I/O *1 

/* append (writes guaranteed at the end) */ 


#ifhdef FDUPFD 
/* fcntl(2) requests */ 

#define F DUPFD 0 

#define F GETFD 1 

#define F SETFD 2 

#define F GETFL 3 

#define F SETFL 4 

#define F_GETOWN 5 /* 
#define F_SETOWN 6 /* 


/* Duplicate Aides */ 
/* Get fildes flags */ 
/* Set fildes flags */ 
/* Get file flags */ 

I* Set file flags *1 
Get owner */ 

Set owner */ 


SETFL- copied from <sys/file.h> */ 

00004 /* non-blocking reads *1 

00010 /* append on each write */ 

00100 /* signal pgrp when data ready */ 

SEE ALSO 

fcntl(2), open(2) 


/* flags for F_GETFL, F 
#define FNDELAY 
#define F APPEND 
#define FASYNC 
#endif 
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NAME 

fs, inode - format of file system volume 
SYNOPSIS 

#include <sys/types.h> 

#include <sys/filsys.h> 

#include <sys/inode.h> 

DESCRIPTION 

Every file system storage volume (disk, nine-track tape, for instance) has a common format for certain vital 
information. Every such volume is divided into a certain number of blocks. The block size is a parameter 


of the file system. 

, Sectors 0 to 15 on a file system are used to contain primary and secondary bootstrapping 

programs. 



The actual file system begins at sector 16 with the super block. The layout of the super block as defined by 

the include file <sys/fs.h> is: 


#define FS MAGIC 0x011954 


struct fs { 



struct 

fs *fs_link; 

/* linked list of file systems */ 

struct 

fs *fs_rlink; 

/* used for incore super blocks */ 

daddrt 

fs_sblkno; 

/* addr of super-block in filesys *1 

daddrt 

fs_cblkno; 

1* offset of cyl-block in filesys */ 

daddrt 

fs_iblkno; 

1* offset of inode-blocks in filesys */ 

daddrt 

fsdblkno; 

I* offset of first data after eg */ 

long 

fs_cgoffset; 

/* cylinder group offset in cylinder */ 

long 

fscgmask; 

1* used to calc mod fs ntrak *1 

timet 

fs_time; 

1* last time written */ 

long 

fs size; 

1* number of blocks in fs */ 

long 

fs dsize; /* number of data blocks in fs */ 

long 

fs_ncg; 

1* number of cylinder groups */ 

long 

fs bsize; 1* size of basic blocks in fs */ 

long 

fs_fsize; 

/* size of frag blocks in fs */ 

long 

fsjrag; 

/* number of frags in a block in fs */ 

/* these are configuration parameters */ 


long 

fsminffee; 

1* minimum percentage of free blocks */ 

long 

fs_rotdelay; 

/* num of ms for optimal next block *1 

long 

fs rps; 

/* disk revolutions per second */ 

I* these fields can be computed from the others */ 

long 

fs_bmask; 

1* “blkoff” calc of blk offsets */ 

long 

fs_fmask; 

1* “fragoff” calc of frag offsets */ 

long 

fs_bshift; 

/* “lblkno” calc of logical blkno */ 

long 

fs_fshift; 

I* “numfrags” calc number of frags */ 

1* these are configuration parameters */ 


long 

fs_maxcontig; 

/* max number of contiguous blks *1 

long 

fsjnaxbpg; 

I* max number of blks per cyl group *1 

/* these fields can be computed from the others */ 

long 

fs_fragshift; 

/* block to frag shift */ 

long 

fs_fsbtodb; 

/* fsbtodb and dbtofsb shift constant */ 

long 

fs_sbsize; 

/* actual size of super block */ 

long 

fs_csmask; 

/* esum block offset */ 

long 

fs_csshift; 

/* esum block number *1 

long 

fsnindir; 

1* value of NINDIR */ 

long 

fs_inopb; 

1* value of INOPB */ 

long 

fsnspf; 

1* value of NSPF */ 

long 

fs_sparecon[6]; 

I* reserved for future constants */ 
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I* sizes determined by number of cylinder groups and their sizes */ 

daddr t fs_csaddr; /* blk addr of cyl grp summary area */ 

long fs cssize; /* size of cyl grp summary area */ 

long fs_cgsize; /* cylinder group size */ 

/* these fields should be derived from the hardware */ 


long 

fs_ntrak; 

/* tracks per cylinder */ 

long 

fs_nsect; 

/* sectors per track */ 

long 

fsspc; 

/* sectors per cylinder */ 

/* this comes from the disk driver partitioning *1 

long 

fs_ncyl; 

/* cylinders in file system */ 

/* these fields can be computed from the others */ 

long 

fscpg; 

1* cylinders per group */ 

long 

fs_ipg; 

/* inodes per group */ 

long 

fs_fyg; 

/* blocks per group * fs frag */ 

/* this data must be re-computed after crashes */ 

struct 

esum fscstotal; 

/* cylinder summary information *1 

/* these fields are 

: cleared at mount time */ 

char 

fsfmod; 

/* super block modified flag */ 

char 

fsclean; 

1* file system is clean flag *1 

char 

fsronly; 

1* mounted read-only flag */ 

char 

fsflags; 

/* currendy unused flag */ 


char fs_fsmnt[MAXMNTLEN]; /* name mounted on */ 

I* these fields retain the current block allocation info */ 

long fscgrotor; /* last eg searched */ 

struct esum *fs_csp[MAXCSBUFS];/* list of fs_cs info buffers */ 

long fs_cpc; /* cyl per cycle in postbl */ 

short fsjpostbl[MAXCPG] [NRPOS];/* head of blocks for each rotation */ 

long fsjnagic; /* magic number */ 

u char fs_rotbl[l] ; /* list of blocks for each rotation */ 

/* actually longer */ 

}; 

Each disk drive contains some number of file systems. A file system consists of a number of cylinder 
groups. Each cylinder group has inodes and data. 

A file system is described by its super-block, which in turn describes the cylinder groups. The super-block 
is critical data and is replicated in each cylinder group to protect against catastrophic loss. This is done at 
file system creation time and the critical super-block data does not change, so the copies need not be refer- 
enced further unless disaster strikes. 

Addresses stored in inodes are capable of addressing fragments of ‘blocks’. File system blocks of at most 
size MAXBSIZE can be optionally broken into 2, 4, or 8 pieces, each of which is addressable; these pieces 
may be DEV BSIZE, or some multiple of a DEV_BSIZE unit. 

Large files consist of exclusively large data blocks. To avoid undue wasted disk space, the last data block 
of a small file is allocated as only as many fragments of a large block as are necessary. The file system for- 
mat retains only a single pointer to such a fragment, which is a piece of a single large block that has been 
divided. The size of such a fragment is determinable from information in the inode, using the “blksizeffs, 
ip, lbn)” macro. 

The file system records space availability at the fragment level; to determine block availability, aligned 
fragments are examined. 

The root inode is the root of the file system. Inode 0 can’t be used for normal purposes and historically bad 
blocks were linked to inode 1, thus the root inode is 2 (inode 1 is no longer used for this purpose, however 
numerous dump tapes make this assumption, so we are stuck with it). The lost+found directory is given 
the next available inode when it is initially created by mkfs. 
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fsjninfree gives the minimum acceptable percentage of file system blocks which may be free. If the freelist 
drops below this level only the super-user may continue to allocate blocks. This may be set to 0 if no 
reserve of free blocks is deemed necessary, however severe performance degradations will be observed if 
the file system is run at greater than 90% full; thus the default value of fsjninfree is 10%. 

Empirically the best trade-off between block fragmentation and overall disk utilization at a loading of 90% 
comes with a fragmentation of 4, thus the default fragment size is a fourth of the block size. 

Cylinder group related limits-. Each cylinder keeps track of the availability of blocks at different rotational 
positions, so that sequential blocks can be laid out with minimum rotational latency. NRPOS is the number 
of rotational positions which are distinguished. With NRPOS 8 the resolution of the summary information 
is 2ms for a typical 3600 rpm drive. 

fs rotdelay gives the minimum number of milliseconds to initiate another disk transfer on the same 
cylinder. It is used in determining the rotationally optimal layout for disk blocks within a file; the default 
value for fsrotdelay is 2ms. 

Each file system has a statically allocated number of inodes. An inode is allocated for each NBPI bytes of 
disk space. The inode allocation strategy is extremely conservative. 

MAXIPG bounds the number of inodes per cylinder group, and is needed only to keep the structure simpler 
by having the only a single variable size element (the free bit map). 

N.B.: MAXIPG must be a multiple of INOPB(fs). 

MINBSIZE is the smallest allowable block size. With a MINBSIZE of 4096 it is possible to create files of 
size 2 A 32 with only two levels of indirection. MINBSIZE must be big enough to hold a cylinder group 
block, thus changes to (struct eg) must keep its size within MINBSIZE. MAXCPG is limited only to 
dimension an array in (struct eg); it can be made larger as long as that structure’s size remains within the 
bounds dictated by MINBSIZE. Note that super blocks are never more than size SBS1ZE. 

The path name on which the file system is mounted is maintained in fs Jsmnt. MAXMNTLEN defines the 
amount of space allocated in the super block for this name. The limit on the amount of summary informa- 
tion per file system is defined by MAXCSBUFS. It is currently parameterized for a maximum of two mil- 
lion cylinders. 

Per cylinder group information is summarized in blocks allocated from the first cylinder group’s data 
blocks. These blocks are read in from fs csaddr (size fs cssize) in addition to the super block. 

N.B.: sizeof (struct esum) must be a power of two in order for the “fs cs” macro to work. 

Super block for a file system: MAXBPC bounds the size of the rotational layout tables and is limited by the 
fact that the super block is of size SBSIZE. The size of these tables is inversely proportional to the block 
size of the file system. The size of the tables is increased when sector sizes are not powers of two, as this 
increases the number of cylinders included before the rotational pattern repeats (fsjcpc). The size of the 
rotational layout tables is derived from the number of bytes remaining in (struct fs). 

MAXBPG bounds the number of blocks of data per cylinder group, and is limited by the fact that cylinder 
groups are at most one block. The size of the free block table is derived from the size of blocks and the 
number of remaining bytes in the cylinder group structure (struct eg). 

Inode: The inode is the focus of all file activity in the UNIX file system. There is a unique inode allocated 
for each active file, each current directory, each mounted-on file, text file, and the root. An inode is 
‘named’ by its device/i-number pair. For further information, see the include file <sys/inode.h>. 
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NAME 

fstab - static information about the filesystems 

SYNOPSIS 

#include <fstab.h> 

NOTE 

This file is obsolete and exists only for compatability. New programs should use mntent( 5) instead. The 
routines for accessing letclfstab are now in getmntentfi). 

DESCRIPTION 

The file letclfstab describes the file systems and swapping partitions on the local machine. It is created by 
the system administrator using a text editor and processed by commands which mount, unmount, check 
consistency of, dump and restore file systems, and by the system in providing swap space. 

It consists of a number of lines of the form: 

fs_spec:fs_file:fs_type:fs_ffeq:fs_passno 
an example of which would be: 

/dev/xyOa:/:rw:l:l 

The entries from this file are accessed using the routines in getfsentfh), which returns a structure of the fol- 
lowing form: 


struct fstab { 
char 

♦fsspec; 

/* block special device name */ 

char 

♦fsfile; 

I* file system path prefix *1 

char 

*fs_type; 

I* rw,ro,sw or xx */ 

int 

fsfreq; 

I* dump frequency, in days *1 

int 

fs_passno; 

I* pass number on parallel dump */ 


}; 

The lines in the file give for each file system or swap area on the local machine the disk partition it is con- 
tained in fsspec and the directory on which it is to be mounted (unless it is a swap area) in fs Jile . The 
fs_spec special file name is the block special file name, and not the character special file name which the 
rest of the entry refers to. If a program needs the character special file name, the program must create it by 
appending a “r” after the last “/” in the special file name. 

The fsjype indicates whether it it to be read-only “ro”, readable and writable “rw”, or readable and writ- 
able subject to quotas “rq”. If fsjype is “sw” then the special file is made available as a piece of swap 
space by the swapon( 8) command at the end of the system reboot procedure. The fields other than fs spec 
and fsjype are not used in this case. If fsjype is “rq” then at boot time the file system is automatically 
processed by the quotacheck(S) command and disk quotas are then enabled with quotaon( 8). File system 
quotas are maintained in a file “quotas”, which is located at the root of the associated file system. If 
fsjype is specified as “xx” the entry is ignored. This is useful to show disk partitions which are currently 
not used. 

The field fs Jreq indicates how often each partition should be dumped by the dump (8) command (and 
triggers that commands w option which tells which file systems should be dumped). Most systems set the 
fs Jreq field to 1 indicating that the file systems are dumped each day. 

The final field fs jassno is used by the disk consistency check program fsck( 8) to allow overlapped check- 
ing of file systems during a reboot. All file systems with fs jassno of 1 are first checked simultaneosly, 
then all file systems with fs jassno of 2, and so on. It is usual to make the fs jassno of the root file system 
have the value 1 and then check one file system on each available disk drive in each subsequent pass to the 
exhaustion of file system partitions. 
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The letclfstab is only read by programs, and not written; it is the duty of the system administrator to prop- 
erly create and maintain this file. The order of records in letclfstab is important because fsck, mount, and 
umount process the file sequentially; file systems must appear after file systems they are mounted within. 

FILES 

/etc/fstab 
SEE ALSO 

getfsent(3), quotacheck(8), quotaon(8) 
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NAME 

ftpusers - list of users prohibited by ftp 

SYNOPSIS 

/usr/etc/ftpusers 

DESCRIPTION 

Ftpusers contains a list of users who cannot access this system using the/tp(l) program. Ftpusers contains 
one user name per line. 

SEE ALSO 

ftp(l), ftpd(8C) 
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NAME 

gettytab - terminal configuration data base 

SYNOPSIS 

/etc/gettytab 

DESCRIPTION 

Gettytab is a simplified version of the termcap(S) data base used to describe terminal lines. The initial ter- 
minal login process getty(8) accesses the gettytab file each time it starts, allowing simpler reconfiguration 
of terminal characteristics. Each entry in the data base is used to describe one class of terminals. 

There is a default terminal class, default, that is used to set global defaults for all other classes. (That is, 
the default entry is read, then the entry for the class required is used to override particular settings.) 

CAPABILITIES 

Refer to termcap( 5) for a description of the file layout. The default column below lists defaults obtained if 
there is no entry in the table obtained, nor one in the special default table. 


Name 

Type Default 

Description 

ap 

bool 

false 

terminal uses any parity 

bd 

num 

0 

backspace delay 

bk 

str 

0377 

alternate end of line character (input break) 

cb 

bool 

false 

use ert backspace mode 

cd 

num 

0 

carriage-return delay 

ce 

bool 

false 

use ert erase algorithm 

ck 

bool 

false 

use ert kill algorithm 

cl 

str 

NULL 

screen clear sequence 

CO 

bool 

false 

console - add \n after login prompt 

ds 

str 

A Y 

delayed suspend character 

ec 

bool 

false 

leave echo off 

ep 

bool 

false 

terminal uses even parity 

er 

sa- 

*? 

erase character 

et 

sh - 

T) 

end of text (EOF) character 

ev 

str 

NULL 

initial enviroment 

fO 

num 

unused 

tty mode flags to write messages 

fl 

num 

unused 

tty mode flags to read login name 

f2 

num 

unused 

tty mode flags to leave terminal as 

fd 

num 

0 

form-feed (vertical motion) delay 

fl 

str 

'0 

output flush character 

he 

bool 

false 

do NOT hangup line on last close 

he 

str 

NULL 

hostname editing string 

hn 

str 

hostname hostname 

ht 

bool 

false 

terminal has real tabs 

ig 

bool 

false 

ignore garbage characters in login name 

im 

str 

NULL 

initial (banner) message 

in 

str 

A C 

interrupt character 

is 

num 

unused 

input speed 

kl 

str 

A U 

kill character 

lc 

bool 

false 

terminal has lower case 

lm 

str 

login: 

login prompt 

In 

str 

A V 

“literal next” character 

lo 

str 

/bin/login program to exec when name obtained 

nd 

num 

0 

newline (line-feed) delay 

nl 

bool 

false 

terminal has (or might have) a newline character 

nx 

str 

default next table (for auto speed selection) 

op 

bool 

false 

terminal uses odd parity 
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os 

num 

unused 

output speed 

pc 

str 

\0 

pad character 

pe 

bool 

false 

use printer (hard copy) erase algorithm 

Pf 

num 

0 

delay between first prompt and following flush (seconds) 

ps 

bool 

false 

line connected to a MICOM port selector 

qu 

sa- 

“\ 

quit character 

rp 

sh - 

Tt 

line retype character 

rw 

bool 

false 

do not use raw for input, use cbreak 

sp 

num 

0 

line speed (input and output) 

su 

sa- 

“Z 

suspend character 

to 

sh" 

none 

table continuation 

td 

num 

0 

tab delay 

to 

num 

0 

timeout (seconds) 

tt 

str 

NULL 

terminal type (for enviroment) 

ub 

bool 

false 

do unbuffered output (of prompts etc) 

uc 

bool 

false 

terminal is known upper case only 

we 

str 

'W 

word erase character 

xc 

bool 

false 

do not echo control chars as “X 

xf 

str 

"S 

XOFF (stop output) character 

xn 

str 

A Q 

XON (start output) character 


If no line speed is specified, speed will not be altered from that which prevails when getty is entered. 
Specifying an input or output speed overrides line speed for stated direction only. 

Terminal modes to be used for the output of the message, for input of the login name, and to leave the ter- 
minal set as upon completion, are derived from the Boolean flags specified. If the derivation should prove 
inadequate, any (or all) of these three may be overriden with one of the ft), fl, or f2 numeric specifications, 
which can be used to specify (usually in octal, with a leading ‘0’) the exact values of the flags. Local (new 
tty) flags are set in the top 16 bits of this (32 bit) value. 

Should getty receive a null character (presumed to indicate a line break) it will restart using the table indi- 
cated by the nx entry. If there is none, it will re-use its original table. 

Delays are specified in milliseconds, the nearest possible delay available in the tty driver will be used. 
Should greater certainty be desired, delays with values 0, 1,2, and 3 are interpreted as choosing that partic- 
ular delay algorithm from the driver. 

The cl screen clear string may be preceded by a (decimal) number of milliseconds of delay required (a la 
termcap). This delay is simulated by repeated use of the pad character pc. 

The initial message, and login message, im and lm may include the character sequence %h to obtain the 
hostname. (% % obtains a single ‘%’ character.) The hostname is normally obtained from the system, but 
may be set by the hn table entry. In either case it may be edited with he. The he string is a sequence of 
characters, each character that is neither ‘@’ nor *#’ is copied into the final hostname. A ‘@’ in the he 
string, causes one character from the real hostname to be copied to the final hostname. A *#’ in the he 
string, causes the next character of the real hostname to be skipped. Surplus ‘@’ and ‘#’ characters are 
ignored. 

When getty execs the login process, given in the lo string (usually "/bin/login"), it will have set the enviro- 
ment to include the terminal type, as indicated by the tt string (if it exists). The ev string, can be used to 
enter additional data into the environment. It is a list of comma separated strings, each of which will 
presumably be of the form name=value . 

If a non-zero timeout is specified, with to, then getty will exit within the indicated number of seconds, 
either having received a login name and passed control to login, or having received an alarm signal, and 
exited. This may be useful to hangup dial in lines. 
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Output from getty is even parity unless op is specified. Op may be specified with ap to allow any parity on 
input, but generate odd parity output. Note: this only applies while getty is being run, terminal driver limi- 
tations prevent a more complete implementation. Getty does not check parity of input characters in RAW 
mode. 

SEE ALSO 

termcap(5), getty(8). 
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NAME 

group - group file 

SYNOPSIS 

/etc/group 

DESCRIPTION 

Group contains for each group the following information: 

° group name 

• encrypted password 

• numerical group ID 

8 a comma separated list of all users allowed in the group 

This is an ASCII file. The fields are separated by colons; each group is separated from the next by a new- 
line. If the password field is null, no password is demanded. 

This file resides in the / etc directory. Because of the encrypted passwords, it can and does have general 
read permission and can be used, for example, to map numerical group ID’s to names. 

A group file can have a line beginning with a plus (+), which means to incorporate entries from the yellow 
pages. There are two styles of + entries: All by itself, + means to insert the entire contents of the yellow 
pages group file at that point; +name means to insert the entry (if any) for name from the yellow pages at 
that point If a + entry has a non-null password or group member field, the contents of that field will 
overide what is contained in the yellow pages. The numerical group ID field cannot be overridden. 

EXAMPLE 

+mypro ject : : :bill, Steve 
+ : 

If these entries appear at the end of a group file, then the group myproject will have members billmdsteve, 
and the password and group ID of the yellow pages entry for the group myproject. All the groups listed in 
the yellow pages will be pulled in and placed after the entry for myproject. 

FILES 

/etc/group /etc/yp/group 
SEE ALSO 

setgroups(2), initgroups(3), crypt(3), passwd(l), passwd(5) 

BUGS 

The passwd(\) command won’t change group passwords. 
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NAME 

hosts - host name data base 

SYNOPSIS 

/etc/hosts 

DESCRIPTION 

The hosts file contains information regarding the known hosts on the DARPA Internet. For each host a sin- 
gle line should be present with the following information: 

Internet address 
official host name 
aliases 

Items are separated by any number of blanks and/or tab characters. A “#’ indicates the beginning of a com- 
ment; characters up to the end of the line are not interpreted by routines which search the file. This file is 
normally created from the official host data base maintained at the Network Information Control Center 
(NIC), though local changes may be required to bring it up to date regarding unofficial aliases and/or unk- 
nown hosts. 

Network addresses are specified in the conventional V notation using the inet addrQ routine from the 
Internet address manipulation library, inet( 3N). Host names may contain any printable character other than 
a field delimiter, newline, or comment character. 

EXAMPLE 

Here is a typical line from the letc/hosts file: 

192.9.1.20 gaia # Alison Shanks 

FILES 

/etc/hosts 

SEE ALSO 

gethostent(3N) 


384 


Last change: 28 August 1985 


Sun Release 3.0 



HOSTS.EQUIV ( 5 ) 


FILE FORMATS 


HOSTS.EQUIV ( 5 ) 


NAME 

hosts.equiv - list of trusted hosts 
DESCRIPTION 

Hosts.equiv resides in directory /etc and contains a list of trusted hosts. When an rlogin( 1) or rsh(\) 
request from such a host is made, and the initiator of the request is in letclpasswd, then no further validity 
checking is done. That is, rlogin does not prompt for a password, and rsh completes successfully. So a 
remote user is “equivalenced” to a local user with the same user ID when the remote user is in 
hosts.equiv . 

The format of hosts.equiv is a list of names, as in this example: 

hostl 

host2 

+@groupl 

-@group2 

A line consisting of a simple host name means that anyone logging in from that host is trusted. A line con- 
sisting of +@group means that all hosts in that network group are trusted. A line consisting of -@group 
means that hosts in that group are not trusted. Programs scan hosts. equiv linearly, and stop at the first hit 
(either positive for hostname and +@ entries, or negative for -@ entries). A line consisting of a single + 
means that everyone is trusted. 

The .r hosts file has the same format as hosts. equiv. When user XXX executes rlogin or rsh, the .r hosts file 
from XXX' s home directory is conceptually concatenated onto the end of hosts. equiv for permission check- 
ing. However, -@ entries are not sticky. If a user is excluded by a minus entry from hosts.equiv but 
included in .rhosts, then that user is considered trusted. In the special case when the user is root, then only 
the /.rhosts file is checked. 

It is also possible to have two entries (separated by a single space) on a line of these files. In this case, if 
the remote host is equivalenced by the first entry, then the user named by the second entry is allowed to log 
in as anyone, that is, specify any name to the -1 flag (provided that name is in the letclpasswd. file, of 
course). Thus 

sundown john 

allows john to log in from sundown as anyone. The usual usage would be to put this entry in the .rhosts file 
in the home directory for bill . Then john may log in as bill when coming from sundown. The second entry 
may be a netgroup, thus 

+@groupl +@group2 

allows any user in group2 coming from a host in groupl to log in as anyone. 

FILES 

/etc/hosts.equiv 

/etc/yp/domain/netgroup 

/etc/yp/do/mw'n/netgroup.byuser 

/etc/yp/dowwm/netgroup.byhost 

SEE ALSO 

rlogin(l), rsh(l), netgroup(5) 
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NAME 

kbd - keyboard translation table format and default table 
SYNOPSIS 

#include <sundev/kbd.h> 


DESCRIPTION 

Keyboard translation is done in the UNIX kernel via a set of tables. A translation table is 128 bytes of 
‘entries’, which are bytes (unsigned chars). The top 4 bits of each entry are decoded by a case statement in 
the keyboard translator. If the entry is less than 0x80, it is sent out as an ASCII character (possibly with the 
META bit OR-ed in). ‘Special’ entries are 0x80 or greater, and invoke more complicated actions, 
struct keymap { 

unsigned char keymap[128]; /* maps keycodes to actions *1 

}; 


A keyboard is defined by its keymaps. 


struct keyboard { 

struct keymap 
struct keymap 
struct keymap 
struct keymap 
struct keymap 
int 
int 

unsigned char 
unsigned char 

}; 


*k_normal; I* Unshifted */ 

♦k shifted; /* Shifted */ 

*k_caps;/* Caps locked */ 

*k_control; /* Controlled */ 

*k_up; /* Key went up */ 

kidleshifts; I* Shifts */ 

k idlebuckys; /* Bucky bits */ 

k abortl ; /* 1st key of abort sequence */ 

k_abort2; I* 2nd key of abort sequence */ 


The following defines the bit positions used within k idleshifts to indicate the ‘pressed’ (1) or ‘released’ 
(0) state of shift keys. The bit numbers and the aggregate masks are defined. 


Since it is possible to have more than one bit in the shift mask on at once, there is an implied priority given 
to each shift state when determining which translation table to use. The order is (from highest priority to 
lowest) UPMASK, CTRLMASK, SHIFTMASK, and lastly CAPSMASK. 


#define CAPSLOCK 0 

#define SHIFTLOCK 1 

#define LEFTSHIFT 2 

#define RIGHTSHIFT 3 

#define LEFTCTRL 4 

#define RIGHTCTRL 5 

#define CAPSMASK 0x0001 

#define SHIFTMASK OxOOOE 

#define CTRLMASK 0x0030 

#define UPMASK 0x0080 


/* Caps Lock key */ 

/* Shift Lock key */ 

/* Left-hand shift key */ 

/* Right-hand shift key */ 

/* Left-hand (or only) control key */ 
/* Right-hand control key */ 

/* Caplock translation table */ 

/* Shifted translation table */ 

/* Ctrl shift translation table */ 

I* Key up translation table */ 


Special Entry Keys 

The ‘special’ entries’ top 4 bits are defined below. Generally they are used with a 4-bit parameter (such as 
a bit number) in the low 4 bits. The bytes whose top 4 bits are 0x0 thru 0x7 happen to be ASCII characters. 
They are not special cased, but just normal cased. 


#define SHIFTKEYS 0x80 

thru 0x8F. This key helps to determine the translation table used. The bit position of its bit in 
‘shiftmask’ is added to the entry, for example, SHIFTKEYS+LEFTCTRL. When this entry is 
invoked, the bit in ‘shiftmask’ is toggled. Depending which tables you put it in, this works well 
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for hold-down keys or press-on, press-off keys. 

#define BUCKYBITS 0x90 

thru 0x9F. This key determines the state of one of the ‘bucky’ bits above the returned ASCII char- 
acter. This is basically a way to pass mode-key-up/down information back to the caller with each 
‘real’ key depressed. The concept, and name ‘bucky’ (derivation unknown) comes from the 
MIT/SAIL ‘TV’ system — they had TOP, META, CTRL, and a few other bucky bits. The bit posi- 
tion of its bit in ‘buckybits’, minus 7, is added to the entry; for example, bit 0x00000400 is BUCK- 
YBITS+3. The ‘-7’ prevents us from messing up the ASCII char, and gives us 16 useful bucky bits. 
When this entry is invoked, the designated bit in ‘buckybits’ is toggled. Depending which tables 
you put it in, this works well for hold-down keys or press-on, press-off keys. 

#define METABIT 0 

Meta key depressed with key. This is the only user accessible bucky bit. This value is added to 
BUCKYBITS in the translation table. 

#define SYSTEMBIT 1 

‘System’ key was down w/key. This is a kernel-accessible bucky bit. This value is added to 
BUCKYBITS in the translation table. The system key is currently not used except as a place holder 
to indicate the key used as the k abortl key (as defined above). 

#define FUNNY OxAO /* thru OxAF. This key does one of 16 funny 

things based on the low 4 bits: *1 
#define NOP OxAO I* This key does nothing. */ 

#define OOPS OxAl /* This key exists but is undefined. */ 

#define HOLE 0xA2 /* This key does not exist on the keyboard. 

Its position code should never be 
generated. This indicates a software/ 
hardware mismatch, or bugs. *1 

#define NOSCROLL 0xA3 /* This key alternately sends A S or A Q */ 

#define CTRLS 0xA4 /* This sends A S and lets NOSCROLL know */ 

#define CTRLQ 0xA5 /* This sends A Q and lets NOSCROLL know */ 

#define RESET 0xA6 /* Kbd was just reset */ 

#define ERROR 0xA7 /* Kbd just detected an internal error */ 

#define IDLE 0xA8 /* Kbd is idle (no keys down) */ 

Combinations 0xA9 to OxAF are reserved for non-parameterized functions. 

#define STRING OxBO 

thru OxBF. The low-order 4 bits index a table select a string to be returned, char by char. Each 
entry in the table is null terminated. 

#define KTAB_STRLEN 10 /* Maximum string length (including null) */ 

Definitions for the individual string numbers: 

#define HOMEARROW 0x00 

#define UP ARROW 0x01 

#define DOWNARROW 0x02 
#define LEFTARROW 0x03 

#define RIGHTARROW 0x04 

String numbers 5 thru F are available to users making custom entries. 
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Function Key Groupings 

In the following function key groupings, the low-order 4 bits indicate the function key number within the 
group: 

#define LEFTFUNC OxCO /* thru OxCF. The ‘left’ group. */ 

#define RIGHTFUNC OxDO /* thru OxDF. The ‘right’ group. */ 

#define TOPFUNC OxEO I* thru OxEF. The ‘top’ group. */ 

#define BOTTOMFUNC OxFO /* thru OxFF. The ‘bottom’ group. */ 

#define LF(n) (LEFTFUNC+(n)-l) 

#defineRF(n) (RIGHTFUNC+(n)-l) 

#define TF(n) (TOPFUNC+(n)-l) 

#define BF(n) (BOTTOMFUNC+(n)-l) 

The actual keyboard positions may not be on the left/right/top/bottom of the physical keyboard (although 
they usually are). What is important is that we have reserved 64 keys for function keys. 

Normally, when a function key is pressed, the following escape sequence is sent through the character 
stream: 

ESC[0..9z 

where ESC is a single escape character and 0..9 indicate some number of digits needed to encode the func- 
tion key as a decimal number. 

DEFAULT TABLES 

The kernel has initial translation tables, one set for each type of keyboard supported, 

#include "../sundev/kbd.h" 

/* handy way to define control characters in the tables */ 

#define c(char) (char&OxlF) 

#define ESC OxlB 


/* Unshifted keyboard table for Micro Switch 103SD32-2 */ 
static struct keymap keytab ms lc = { 


/* 0*/ 

HOLE, 

BUCKYBITS+SYSTEMBIT, 







LF(2), 

LF(3), HOLE, TF(1), 

TF(2), 

TF(3), 

1* 8 */ 

TF(4), 

TF(5), 

TF(6), 

TF(7), 

TF(8), TF(9), TF(10), 

TF(ll), 


/* 16 */ 

TF(12), TF(13), TF(14), 

c(T), 

HOLE, RF(1), ’+’, 

9 9 

9 


/* 24 */ 

HOLE, 

LF(4), 


LF(6), 

HOLE, SHIFTKEYS+CAPSLOCK, 

9 1 9 

/* 32 */ 

’3’, 

’4’, 

’5’, 

’6’, 

’7’, ’8’, ’9’, 

r , 

’O’, 

^ , 

/* 40 */ 

> > 

9 

>-> 

9 

9 0 

9 

’\b’, 

HOLE, ’7’, ’8’, 

’9’, 


/* 48 */ 

HOLE, 

LF(7), 

STRING+UPARROW, 








LF(9), HOLE, ’\t’, 

’q’. 

’w’. 

/* 56 */ 

’e’, 

’r’, 

’t’, 

y. 

’u’, ’i’, ’o’, 

>_ J 

P . 


/* 64 */ 



9 9 

9 

HOLE, 

’4’, ’5’, ’6’, 

HOLE, 


/* 72 */ 

STRING+LEFT ARROW, 






STRING+HOME ARROW, 

STRING+RIGHTARROW, 

HOLE, SHIFTKEYS+SHIFTLOCK, 

’a’ ’s’ ’d’ 

/* 80 */ ’f’, ’g’, ’h’, ’j’, ’k’, T, 

/*88*/ T, V, HOLE, ’1’, ’2’, ’3’, HOLE, NOSCROLL, 

/* 96 */ STRING+DOWN ARROW, 

LF(15), HOLE, HOLE, SHIFTKEYS+LEFTSHIFT, 
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/=♦= 104 */ 
/*112 */ 
I * 120 */ 


}; 


’z’, ’x’, ’c’, 

V, ’b’, ’n’, ’m’, 7’, SHIFTKEYS+RIGHTSHIFT, 

NOP, 0x7F, ’O’, NOP, HOLE, HOLE, HOLE, 

HOLE, HOLE, SHIFTKEYS+LEFTCTRL, 

’ ’, SHIFTKEYS+RIGHTCTRL, 

HOLE, HOLE, IDLE, 


/* Shifted keyboard table for Micro Switch 103SD32-2 */ 


static struct keymap keytabmsuc = { 

/* 0*/ HOLE, BUCKYBITS+SYSTEMBIT, 





LF(2), 

LF(3), 

HOLE, 

TF(1), 

TF(2), 

TF(3), 

1 * 8 */ 

TF(4), TF(5), 

TF(6), 

TF(7), 

TF(8), 

TF(9), 

TF(10), 

TF(ll), 


1 * 16 */ 

TF(12), TF(13), TF(14), 

c(T), 

HOLE, 

RF(1), 

’+’, 

9 9 

9 


1 * 24 */ 

HOLE, LF(4), 

’\f\ 

LF(6), 

HOLE, 

SHIFTKEYS+CAPSLOCK, 

9 1 9 9119 

1 * 32 */ 




Y\ 



’O’, 

9 

1 * 40 */ 

J _J >A> 

“ » 9 


’\b’. 

HOLE, 

’7’, 

’8’, 

’9’, 


1 * 48 */ 

HOLE, LF(7), 

STRING+UP ARROW, 









LF(9), 

HOLE, 

’\t’, 

’Q’, 

’W’, 

1 * 56 */ 

’E’, ’R’, 

>T’, 

’Y’, 

’U’, 

T. 

’O’, 

’P’, 


1 * 64 */ 

T, 

J 9 
9 

HOLE, 

’4’, 

’5’, 

’6’, 

HOLE, 



/* 72 */ STRING+LEFT ARROW, 

STRING+HOME ARROW, 

STRING+RIGHTARROW, 

HOLE, SHIFTKEYS+SHIFTLOCK, 
’A’, ’S’, ’D’, 


1* 80 *1 

’F, 

’G\ 

’H’, ’J’, 

’K\ ’L’, ’+’, 


1* 88 */ 

’W, 

V, 

HOLE, ’1’, 

’2’, ’3’, HOLE, 

NOSCROLL, 

1* 96 *1 

STRING+DOWN ARROW, 






LF(15), HOLE, 

HOLE, SHIFTKEYS+LEFTSHIFT, 





’Z’, 

’X’, ’C\ 

/* 104 *1 

’V’, 

’B’, 

’N’, ’M’, 

’<’, ’>’, 

SHIFTKEYS+RIGHTSHIFT, 

1* 112 *1 

NOP, 

0x7F, 

’O’, NOP, 

HOLE, HOLE, 

HOLE, 

1* 120 *1 

HOLE, 

HOLE, 

SHIFTKEYS+LEFTCTRL, 



SHIFTKEYS+RIGHTCTRL, 

HOLE, HOLE, IDLE, 


}; 


I* Caps Locked keyboard table for Micro Switch 103SD32-2 */ 


static struct keymap keytab ms cl = { 

I* 0*/ HOLE, BUCKYBITS+SYSTEMBIT, 

LF(2), LF(3), HOLE, TF(1), TF(2), TF(3), 
/* 8 */ TF(4), TF(5), TF(6), TF(7), TF(8), TF(9), TF(10), TF(ll), 

1*16*1 TF(12), TF(13), TF(14), c(’[’), HOLE, RF(1), ’+’, 

/* 24 */ HOLE, LF(4), ’\f, LF(6), HOLE, SHIFTKEYS+CAPSLOCK, 

’ 1 ’, ’ 2 ’, 

’O’, 

’9’, 


1* 32 *1 

’3’, 

’4’, 

’5’, ’6’, ’7’, ’8', 

’9’, 

t* 40 *1 

9 9 

9 

9-9 

» 

’”, ’\b’, HOLE, ’7’, 

’8’, 

1* 48 */ 

HOLE, 

LF(7), 

STRING+UPARROW, 
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/* 56 */ 
/* 64 */ 
/* 72 */ 


/* 80 */ 
/* 88 */ 
/* 96 */ 


/*104 */ 
/*112 */ 
1 * 120*1 


}; 


’Q’, 

’P\ 

HOLE, 


’W’, 


LF(9), HOLE, ’\t’, 

’E\ ’R’, ’T’, ’Y’, ’U’, T, ’O’, 

T, HOLE, ’4’, ’5’, ’6’, 

STRING+LEFT ARROW, 

STRING+HOME ARROW, 

STRING+RIGHTARROW, 

HOLE, SHIFTKEYS+SHIFTLOCK, 
’A’, ’S’, ’D’, 

F’, ’G’, ’H’ ’J’ ’K’ ’L’ ’•’ ’■’ 

I’, V, HOLE, ’1’, ’2’, ’3’,’ HOLE, NOSCROLL, 

STRING+DOWN ARROW, 

LF(15), HOLE, HOLE, SHIFTKEYS+LEFTSHIFT, 


>F> 


’ v ’> ’ B ’> ’ N ’> ’M’, 7’, SHIFTKEYS+RIGHTSHIFT, 

NOP, 0x7F, ’O’, NOP, HOLE, HOLE, HOLE, 

HOLE, HOLE, SHIFTKEYS+LEFTCTRL, 

’ ’, SHIFTKEYS+RIGHTCTRL, 

HOLE, HOLE, IDLE, 


I* Controlled keyboard table for Micro Switch 103SD32-2 */ 


static struct keymap keytab ms ct = { 


/* o*/ 

/* 8 */ 
/* 16 */ 
I* 24 */ 

/* 32 */ 
/* 40 */ 
/* 48 *1 

/* 56 */ 
/* 64 */ 
I* 12 *1 


/* 80 */ 
/* 88 */ 


HOLE, BUCKYBITS+SYSTEMBIT, 

LF(2), LF(3), HOLE, TF(1), TF(2), TF(3), 
TF(4), TF(5), TF(6), TF(7), TF(8), TF(9), TF(10), TF(ll), 

TF(12), TF(13), TF(14), c(’[’), HOLE, RF(1), OOPS, OOPS, 

HOLE, LF(4), ’\f, LF(6), HOLE, SHIFTKEYS+CAPSLOCK, 

OOPS OOPS 

OOPS, OOPS, OOPS, OOPS, OOPS, OOPS, OOPS, oops! 

OOPS, cC’), c(’@’), ’\b’, HOLE, OOPS, OOPS, OOPS, 

HOLE, LF(7), STRING+UP ARROW, 

LF(9), HOLE, ’\t’, CTRLQ,c(’W’), 

c(’E’), c(’R’), c(’T’), c(’Y’), c(’U’), c(’I’), c(’O’), c(’P’), 

c(T). c(T), c(’_’), HOLE, OOPS, OOPS, OOPS, HOLE, 

STRING+LEFT ARROW, 

STRING+HOME ARROW, 

STRING+RIGHTARROW, 

HOLE, SHIFTKEYS+SHIFTLOCK, 

rt’AM PTRT 

c(’F’), c(’G’), c(’H’), c(’J’), c(’K’), c(’L’), OOPs’, OOPS,’ 

c(’W’), 


/* 96 */ 


/*104 */ 
I* 112 */ 
1*120 */ 


}; 


V, HOLE, OOPS, OOPS, OOPS, HOLE, NOSCROLL, 
STRING+DOWN ARROW, 

LF(15), HOLE, HOLE, SHIFTKEYS+LEFTSHIFT, 

c(’Z’), c(’X’) c(’C’) 

c(’V’), c(’B’), c(’N’), c(’M’), OOPS, OOPS, OOPS, SHIFTKEYS+RIGHTSHIFT, 
NOP, 0x7F, OOPS, NOP, OOPS, HOLE, HOLE, HOLE, 

HOLE, HOLE, SHIFTKEYS+LEFTCTRL, 

’\0’, SHIFTKEYS+RIGHTCTRL, 

HOLE, HOLE, IDLE, 
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/* "Key Up” keyboard table for Micro Switch 103SD32-2 *1 


static struct keymap keytab ms up = { 


/* 0*1 

HOLE, 

BUCKYBITS+SYSTEMBIT, 









OOPS, 

OOPS, 

HOLE, 

OOPS, 

OOPS, 

OOPS, 

1* 8 */ 

OOPS, 

OOPS, 

OOPS, 

OOPS, 

OOPS, 

OOPS, 

OOPS, 

OOPS, 


/* 16 */ 

OOPS, 

OOPS, 

OOPS, 

NOP, 

HOLE, 

OOPS, 

NOP, 

NOP, 


1* 24 */ 

HOLE, 

OOPS, 

NOP, 

OOPS, 

HOLE, 

SHIFTKEYS+CAPSLOCK, 









NOP, 

NOP, 

1* 32 */ 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 


/* 40 */ 

NOP, 

NOP, 

NOP, 

NOP, 

HOLE, 

NOP, 

NOP, 

NOP, 


/* 48 */ 

HOLE, 

OOPS, 

NOP, 

OOPS, 

HOLE, 

NOP, 

NOP, 

NOP, 


/* 56 *1 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 


1* 64 */ 

NOP, 

NOP, 

NOP, 

HOLE, 

NOP, 

NOP, 

NOP, 

HOLE, 


/* 72 */ 

NOP, 

NOP, 

NOP, 

HOLE, 

SHIFTKEYS+SHIFTLOCK, 









NOP, 

NOP, 

NOP, 

1* 80 */ 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 


/* 88 */ 

NOP, 

NOP, 

HOLE, 

NOP, 

NOP, 

NOP, 

HOLE, 

NOP, 


1* 96 */ 

NOP, 

OOPS, 

HOLE, 

HOLE, 

SHIFTKEYS+LEFTSHIFT, 









NOP, 

NOP, 

NOP, 

/*104 */ 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

SHIFTKEYS+RIGHTSHIFT, 

1* 112 */ 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

HOLE, 

HOLE, 

HOLE, 


1* 120*/ 

HOLE, 

HOLE, 

SHIFTKEY S+LEFTCTRL, 





NOP, SHIFTKEYS+RIGHTCTRL, 

HOLE, HOLE, RESET, 


}; 


/* Index to keymaps for Micro Switch 103SD32-2 */ 
static struct keyboard keyindexms = { 
&keytab_ms_lc, 

&keytab_ms_uc, 

&keytab_ms_cl, 

&keytab_ms_ct, 

&keytab_ms_up, 


CTLSMASK, 

0x0000, 

L 77, 
0x0000, 


/* Shift bits which stay on with idle keyboard */ 
/* Bucky bits which stay on with idle keyboard */ 
/* abort keys */ 

/* Shift bits which toggle on down event */ 


}; 


I* Unshifted keyboard table for Sun-2 keyboard */ 


static struct keymap keytab_s2_lc = { 


/* 0*/ 

HOLE, 

BUCKYBITS+SYSTEMBIT, 




/* 8 *1 

TF(3), 

TF(12), 

TF(4), 

LF(ll), 

TF(13), 

LF(2), 

TF(5), 

HOLE, 

TF(14), 

TF(1), 

TF(6), 

TF(2), TF(ll), 
TF(15), 

/* 16 */ 

TF(7), 

TF(8), 

TF(9), 

TF(10), 

HOLE, 

RF(l), 

RF(2), 

RF(3), 

/* 24 */ 

HOLE, 

LF(3), 

LF(4), 

LF(12), 

HOLE, 

c(’t’), 

’1’, 

’2’, 

/* 32 */ 

’3’, 

’4’, 

’5’, 

’6’, 

’7’, 

’8’, 

’9’, 

’O’, 

/* 40 *1 

5 1 

9 

> 9 

~ 9 

>«> 

9 

’\b’, 

HOLE, 

RF(4), 

RF(5), 

RF(6), 

1* 48 */ 

HOLE, 

LF(5), 

LF(13), 

LF(6), 

HOLE, 

’\t’, 

’q’, 

’w’, 

/* 56 */ 

’e’, 

V, 

’t’, 

’y\ 

V, 

'i’, 

’o’. 

5 

P . 
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1*64*1 0x7F, HOLE, RF(7), STRING+UPARROW, 

RF(9), HOLE, 

I* 72 */ LF(7), LF(8), LF(14), HOLE, SHIFTKEYS+LEFTCTRL, 

’a’ ’s’ ’d’ 

/* 80 */ T, ’g’, ’h’, ’j’, ’k’, T, ’\’\ 

I* 88 */ ’W, ’\r’, HOLE, STRING+LEFTARROW, 

RF(ll), STRING+RIGHTARROW, 
HOLE, LF(9), 

I* 96 */ LF(15), LF(10), HOLE, SHIFTKEYS+LEFTSHIFT, 


/*104 */ ’b’, V, ’m’, 


’z\ ’x’, ’c\ ’v’, 

7’, SHIFTKEYS+RIGHTSHIFT, 


/*112*/ RF(13), STRING+DOWN ARROW, 

RF(15), HOLE, HOLE, HOLE, HOLE, HOLE, 
/*120 */ BUCKYBITS+METABIT, 

’ ’, BUCKYBITS+METABIT, 

HOLE, HOLE, HOLE, ERROR, IDLE, 


/* Shifted keyboard table for Sun-2 keyboard */ 


static struct keymap keytab_s2_uc = { 

/* 0*/ HOLE, BUCKYBITS+SYSTEMBIT, 

LF(ll), LF(2), HOLE, TF(1), TF(2), TF(ll), 

/* 8 */ TF(3), TF(12), TF(4), TF(13), TF(5), TF(14), TF(6), TF(15), 

/* 16 */ TF(7), TF(8), TF(9), TF(10), HOLE, RF(1), RF(2), RF(3), 

/* 24 */ HOLE, LF(3), LF(4), LF(12), HOLE, c(’[’), ’!’, 

/* 32 */ ’#’, ’$’, ’%’, ’*’, 

/* 40 */ ’\b’, HOLE, RF(4), RF(5), RF(6), 

/* 48 */ HOLE, LF(5), LF(13), LF(6), HOLE, ’\t’, ’Q’, ’W’, 

/* 56 */ ’E\ ’R’, ’T’, ’Y’, ’U’, T, ’O’, ’P’, 

/* 64 */ ’{’, ’}’, 0x7F, HOLE, RF(7), STRING+UPARROW, 

RF(9), HOLE, 

/* 72 */ LF(7), LF(8), LF(14), HOLE, SHIFTKEYS+LEFTCTRL, 

’A’, ’S’, ’D’ 

/* 80 */ ’F’, ’G’, ’H’, ’J’, ’K’, ’L’, 

/* 88 */ T, V, HOLE, STRING+LEFTARROW, 

RF(ll), STRING+RIGHTARROW, 
HOLE, LF(9), 

/* 96 */ LF(15), LF(10), HOLE, SHIFTKEYS+LEFTSHIFT, 

’Z* ’X’ ’V’ 

/*104 */ ’B\ ’N’, ’M’, ’<’, ’>’, ’?’, SHIFTKEYS+RIGHTSHIFT, 

’\n’, 

/* 1 12 */ RF(13), STRING+DOWN ARROW, 

RF(15), HOLE, HOLE, HOLE, HOLE, HOLE, 
/*120 */ BUCKYBITS+METABIT, 

’ ’, BUCKYBITS+METABIT, 

HOLE, HOLE, HOLE, ERROR, IDLE, 


/* Caps Locked keyboard table for Sun-2 keyboard */ 


392 


Last change: 19 March 1984 


Sun Release 3.0 



KBD(5) 


FILE FORMATS 


KBD(5) 


static struct keymap keytab_s2_cl = { 

/* 0*/ HOLE, BUCKYBITS+SYSTEMBIT, 






LF(ll), LF(2), HOLE, TF(1), 

TF(2), 

TF(ll), 

1* 8*/ 

TF(3), 

TF(12), 

TF(4), 

TF(13), TF(5), TF(14), TF(6), 

TF(15), 


1* 16 */ 

TF(7), 

TF(8), 

TF(9), 

TF(10), HOLE, RF(1), RF(2), 

RF(3), 


1* 24 */ 

HOLE, 

LF(3), 

LF(4), 

LF(12), HOLE, c(’[’), ’1’, 

’2’, 


1* 32 *1 

’3’, 

’4’, 

’5’, 

’6’, ’7’, ’8’, ’9’, 

’O’, 


1* 40 *t 

J > 

“ 9 

J 9 

» 

9 19 

9 

’\b’, HOLE, RF(4), RF(5), 

RF(6), 


1* 48 *1 

HOLE, 

LF(5), 

LF(13), 

LF(6), HOLE, ’\t’, ’Q’, 

’W’, 


I* 56 *1 

’E’, 

’R’, 

’T’, 

’Y’, ’U’, T, ’O’, 

’P’, 


1*64*1 

T, 

T, 

0x7F, 

HOLE, RF(7), STRING+UP ARROW, 







RF(9), 

HOLE, 

1* 72 */ 

LF(7), 

LF(8), 

LF(14), 

HOLE, SHIFTKEYS+LEFTCTRL, 






’A’, 

’S’, 

’D’, 

1* 80 *1 

’F, 

’G’, 

’H’, 

9T9 >T 9 9.9 

J 9 j f y 



1* 88 */ 

’W, 

V, 

HOLE, 

STRING+LEFT ARROW, 







RF(ll), STRING+RIGHTARROW, 






HOLE, 

LF(9), 

1* 96 */ 

LF(15), 

LF(10), 

HOLE, 

SHIFTKEYS+LEFTSHIFT, 







’Z’, ’X’, 

’C’, 

’V’, 

M04 */ 

’B’, 

’N’, 

’M’, 

’,’, 7’, SHIFTKEYS+RIGHTSHIFT, 


’\n’. 


/*112 */ 
1 * 120 */ 


}; 


RF(13), STRING+DOWN ARROW, 

RF(15), HOLE, HOLE, HOLE, HOLE, HOLE, 
BUCKYBITS+METABIT, 

’ ’, BUCKYBITS+METABIT, 

HOLE, HOLE, HOLE, ERROR, IDLE, 


/* Controlled keyboard table for Sun-2 keyboard */ 


static struct keymap keytab_s2_ct = { 


/* 0 */ 

HOLE, 

BUCKYBITS+SYSTEMBIT, 



1* 8 */ 

TF(3), 

TF(12), 

TF(4), 

LF(ll), 

TF(13), 

LF(2), HOLE, TF(1), 
TF(5), TF(14), TF(6), 

TF(2), 

TF(15), 

TF(ll), 

I* 16 */ 

TF(7), 

TF(8), 

TF(9), 

TF(10), 

HOLE, RF(1), RF(2), 

RF(3), 


1* 24 */ 

HOLE, 

LF(3), 

LF(4), 

LF(12), 

HOLE, c(’[’), ’1’, 

c(’@’), 


1* 32 */ 

’3’, 

’4’, 

’5’, 


’7’, ’8’, ’9’, 

’O’, 


/* 40 */ 

c(’ ’), 

9 _9 
— 9 


’\b\ 

HOLE, RF(4), RF(5), 

RF(6), 


1* 48 *1 

HOLE, 

LF(5), 

LF(13), 

LF(6), 

HOLE, ’\t’, c(’q’), 

c(’w’), 


/* 56 */ 

c(’e’), 

c(’r’). 

c(’t’), 

c(’y’). 

c(’u’), c(’i’), c(’o’), 

c(’p’). 


1* 64 */ 

c(T), 

c(T), 

0x7F, 

HOLE, 

RF(7), STRING+UPARROW, 


I* 72 */ 

LF(7), 

LF(8), 

LF(14), 

HOLE, 

RF(9), 

SHIFTKEYS+LEFTCTRL, 

HOLE, 

1* 80 */ 

c(’f), 

c(’g’), 

c(’h’), 

c(’j’), 

c(’a’), 

c(’k’), c(T), 

c(’s’), 

c(’d’), 

/* 88 *1 

c(’W’), 


’\r’, 

HOLE, 

STRING+LEFT ARROW, 



RF(ll), STRING+RIGHTARROW, 
HOLE, LF(9), 

I* 96 *1 LF(15), LF(10), HOLE, SHIFTKEYS+LEFTSHIFT, 

C(’z’), c(’x’), c(’c’), c(’v’), 

/=*= 104 */ c(’b’), c(’n’), c(’m’), c(’_’), SHIFTKEYS+RIGHTSHIFT, 
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/=*= 1 12 */ 
/*120 */ 


}; 


RF(13), STRING+DOWN ARROW, 

RF(15), HOLE, HOLE, HOLE, 
BUCKYBITS+METABIT, 

c(’ ’), BUCKYBITS+METABIT, 

HOLE, HOLE, HOLE, 


’\n’, 

HOLE, HOLE, 


ERROR.IDLE, 


/* "Key Up" keyboard table for Sun-2 keyboard */ 


static struct keymap keytab_s2_up = { 

I* 0*/ HOLE, BUCKYBITS+SYSTEMBIT, 






OOPS, 

OOPS, 

HOLE, 

OOPS, 

OOPS, 

OOPS, 

/* 8*/ 

OOPS, 

OOPS, 

OOPS, 

OOPS, 

OOPS, 

OOPS, 

OOPS, 

OOPS, 


/* 16 */ 

OOPS, 

OOPS, 

OOPS, 

OOPS, 

HOLE, 

OOPS, 

OOPS, 

NOP, 


/* 24 */ 

HOLE, 

OOPS, 

OOPS, 

OOPS, 

HOLE, 

NOP, 

NOP, 

NOP, 


/* 32 */ 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 


/* 40 */ 

NOP, 

NOP, 

NOP, 

NOP, 

HOLE, 

OOPS, 

OOPS, 

NOP, 


/* 48 */ 

HOLE, 

OOPS, 

OOPS, 

OOPS, 

HOLE, 

NOP, 

NOP, 

NOP, 


/* 56 */ 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 


/* 64 */ 

NOP, 

NOP, 

NOP, 

HOLE, 

OOPS, 

OOPS, 

NOP, 

HOLE, 


/* 72 */ 

OOPS, 

OOPS, 

OOPS, 

HOLE, 

SHIFTKE Y S +LEFTCTRL, 









NOP, 

NOP, 

NOP, 

/* 80 */ 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 


1* 88 */ 

NOP, 

NOP, 

HOLE, 

OOPS, 

OOPS, 

NOP, 

HOLE, 

OOPS, 


/* 96 */ 

OOPS, 

OOPS, 

HOLE, 

SHIFTKEYS+LEFTSHIFT, 









NOP, 

NOP, 

NOP, 

NOP, 

/*104 */ 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

SHIFTKEYS+RIGHTSHIFT, 










NOP, 

/* 1 12 */ 

OOPS, 

OOPS, 

NOP, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 



/*120 */ BUCKYBITS+METABIT, 

NOP, BUCKYBITS+METABIT, 

HOLE, HOLE, HOLE, HOLE, RESET, 


}; 


/* Index to keymaps for Sun-2 keyboard */ 
static struct keyboard keyindex_s2 = { 
&keytab_s2_lc, 
&keytab_s2_uc, 
&keytab_s2_cl, 
&keytab_s2_ct, 
&keytab_s2_up, 


}; 


CAPSMASK, 

0x0000, 

1, 77, 

0x0000, 


/* Shift bits which stay on with idle keyboard */ 
/* Bucky bits which stay on with idle keyboard */ 
/* abort keys */ 

/* Shift bits which toggle on down event */ 


/* Unshifted keyboard table for "VT100 style" */ 
static struct keymap keytab_vt_lc = { 
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/* 0*/ HOLE, BUCKYBITS+SYSTEMBIT, 

HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, 

/* 8*/ HOLE, HOLE, STRING+UPARROW, 

STRING+DOWN ARROW, 

STRING+LEFT ARROW, 

STRING+RIGHTARROW, 
HOLE, TF(1), 


/* 16 */ 

TF(2), 

TF(3), TF(4), c(T), ’1’, 

’2’, ’3’, 

’4’, 


/* 24 */ 

’5’, 

’6’, ’7’, ’8’, ’9’, 

’O’, 

9 9 

— 9 


/* 32 */ 

9 ( 9 

9 

c(’H’), BUCKYBITS+MET ABIT, 





’7’, 

bs 

oo 

9 9 

9 

’\t’, 

/* 40 */ 

9 _ 5 

q . 

’w’, ’e’, ’r’, ’t’, 

y, ’u’, 

’i’, 


/* 48 *1 

’o’, 

’P’, T, T, 0x7F, 

’4’, ’5’, 

’6’, 


/* 56 */ 

9 9 

9 9 

SHIFTKEYS+LEFTCTRL, 






SHIFTKEYS+CAPSLOCK, 





’a’, 

’s’, ’d’, 

’f. 

’g’. 

1*64*1 

’h’, 

9^.9 919 9.9 

J 9 9 1 9 9 9 

’\”, V, 

’W\ 


/* 72 *( 

’1’, 

’2’, ’3’, NOP, NOSCROLL, 





SHIFTKEYS+LEFTSHIFT, 

9„9 

/* 80 *1 

’c’, 

>„> >LJ J_J 

v , b , n , m , 

9 9 9 9 

9 9 *9 

* » 

A , 

I* 88 */ 

SHIFTKEYS+RIGHTSHIFT, 






’\n’, ’O’, HOLE, 

9 9 9^.9 

•9 U > 

HOLE, 

HOLE, 

/* 96 */ 

HOLE, 

HOLE, ’ ’, HOLE, HOLE, 

HOLE, HOLE, 

HOLE, 


/*104 */ 

HOLE, 

HOLE, HOLE, HOLE, HOLE, 

HOLE, HOLE, 

HOLE, 


/*112 */ 

HOLE, 

HOLE, HOLE, HOLE, HOLE, 

HOLE, HOLE, 

HOLE, 


1*120*/ 

HOLE, 

HOLE, HOLE, HOLE, HOLE, 

HOLE, HOLE, 

IDLE, 



}; 


/* Shifted keyboard table for "VT100 style” */ 

static struct keymap keytab_vt_uc = { 

/* 0*/ HOLE, BUCKYBITS+SYSTEMBIT, 

HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, 

/* 8 */ HOLE, HOLE, STRING+UPARROW, 

STRING+DOWN ARROW, 

STRING+LEFT ARROW, 

STRING+RIGHTARROW, 
HOLE, TF(1), 


1* 16 */ 

TF(2), 

TF(3), 

TF(4), 

c(T), ’!’, 

’<§>’, 



/* 24 */ 


) A J 

9 




> 5 

9 


/* 32 */ 

> 

c(’H’), 

BUCKYBITS+METABIT 

9 







’7’, 

’8’, 

’9’, 

9 9 

9 

/* 40 */ 

’Q’, 

’W’, 

’E’, 

’R’, ’T’, 

’Y\ 

’U’, 

’I’, 

1* 48 */ 

’O’, 

’P’, 


o 

X 

►Tj 

’4’, 

’5’, 

’6’, 

/* 56 */ 

9 9 

9 9 

SHIFTKEYS+LEFTCTRL, 








SHIFTKEYS+CAPSLOCK, 






’A’, 

’S’, 

’D’, 

’F’, 

/* 64 */ 

’H’, 

’J’, 

’K’, 

>T > >.» 

, • 9 

>n > 

9 

V, 

T* 

/* 72 */ 

’1’, 

’2’, 

’3’, 

NOP, NOSCROLL, 




SHIFTKEYS+LEFTSHIFT, 
’Z’, ’X’, 
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/* 80 */ 
/* 88 */ 

/* 96 */ 
/*104 */ 
/*112 */ 
1 * 120 */ 
}; 


’C’, ’V’, ’B’, ’N’, ’M’, 

SHIFTKEYS+RIGHTSHIFT, 

’\n’, ’O’, HOLE, 

HOLE, HOLE, ’ ’, HOLE, HOLE, 
HOLE, HOLE, HOLE, HOLE, HOLE, 
HOLE, HOLE, HOLE, HOLE, HOLE, 
HOLE, HOLE, HOLE, HOLE, HOLE, 


HOLE, 

HOLE, 

HOLE, 

HOLE, 


V, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 


• 9 


HOLE, HOLE, 
HOLE, 

HOLE, 

HOLE, 

IDLE, 


I* Caps Locked keyboard table for "VT100 style” *1 

static struct keymap keytabvtcl = { 

/* 0 *1 HOLE, BUCKYBITS+SYSTEMBIT, 

HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, 

/* 8 */ HOLE, HOLE, STRING+UPARROW, 

STRING+DOWN ARROW, 

STRING+LEFT ARROW, 

STRING+RIGHTARROW, 
HOLE, TF(1), 


1* 16 */ 

TF(2), 

TF(3), TF(4), c(’[’). 

’1’, 

’2’, ’3’, 

’4’, 


1* 24 */ 

’5’, 

’6’, ’7’, ’8’, 

’9’, 

’O’, 

9 _9 
~ 9 


I* 32 */ 

XI 

9 

c(’H’), BUCKYBITS+METABIT, 






’7’, 

’8’, ’9’, 

9 9 

9 

’\t\ 

/* 40 */ 

’Q’, 

’W’, ’E’, ’R’, 

’T’, 

’Y\ ’U\ 

T, 


/* 48 */ 

’O’, 

’P’, ’[’, ’]’, 

0x7F, 

’4’, ’5’, 

’6’, 


/* 56 *1 

> i 

i i 

SHIFTKEY S+LEFTCTRL, 






SHIFTKEYS+CAPSLOCK, 






’A’, 

’S’, ’D’, 

’F’, 

’G’, 

/* 64 */ 

’H’, 

’J’, ’K’, ’L’, 

1 ,) 

» 9 

’\”, V, 

’W’, 


1* 72 */ 

’1’, 

’2’, ’3’, NOP, 

NOSCROLL, 







SHIFTKEYS+LEFTSHIFT, 






’Z’, 

’X’, 

1* 80 */ 

’C’, 

’V’, ’B’, ’N’, 

’M’, 

> I 9 9 

9 9 *9 



/* 88 */ 

SHIFTKEYS+RIGHTSHIFT, 







’\n’, ’O’, 

HOLE, 

9 9 9K 9 

•9 9 

HOLE, 

HOLE, 

I* 96 */ 

HOLE, 

HOLE, ’ ’, HOLE, 

HOLE, 

HOLE, HOLE, 

HOLE, 


/*104 */ 

HOLE, 

HOLE, HOLE, HOLE, 

HOLE, 

HOLE, HOLE, 

HOLE, 


/*112 */ 

HOLE, 

HOLE, HOLE, HOLE, 

HOLE, 

HOLE, HOLE, 

HOLE, 


1* 120*1 

HOLE, 

HOLE, HOLE, HOLE, 

HOLE, 

HOLE, HOLE, 

IDLE, 



}; 


/* Controlled keyboard table for "VT100 style" */ 


static struct keymap keytab_vt_ct = { 

/* 0*/ HOLE, BUCKYBITS+SYSTEMBIT, 

HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, 

/* 8*/ HOLE, HOLE, STRING+UPARROW, 

STRING+DOWN ARROW, 

STRING+LEFT ARROW, 

STRING+RIGHTARROW, 
HOLE, TF(1), 

/* 16 */ TF(2), TF(3), TF(4), c(T), ’1’, c(’@’), ’3’, ’4’, 


/* 24 */ 


’5’, cr’)> ’7’, ’8’, ’9’, ’O’, c(’_’), ’=’, 
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/* 32 */ c(’ A ’) ) c(’H’), BUCKYBITS+METABIT, 

’7’, ’8\ ’9’, ’\t’, 

/* 40 */ CTRLQ,c(’W’), c(’E’), c(’R’), c(’T’), c(’Y’), c(’U’), c(T), 

/* 48 */ c(’O’), c(’P’), c(’[’), c(T), 0x7F, ’4’, ’5’, ’6’, 

/* 56 */ SHDFTKEYS+LEFTCTRL, 

SHIFTKEYS+CAPSLOCK, 

c(’A’), CTRLS, c(’D’), c(’F’), c(’G’), 

/* 64 */ c(’H’), c(’J’), c(’K’), c(’L’), V, c(’W’), 

/* 72 */ ’V, ’2’, ’3’, NOP, NOSCROLL, 

SHIFTKEYS+LEFTSHIFT, 
c(’Z’), c(’X’), 

/* 80 */ c(’C’), c(’V’), c(’B’), c(’N’), c(’M’), V, c(’_’), 

/* 88 */ SHIFTKEYS+RIGHTSHIFT, 

’\n’, ’O’, HOLE, V, V, HOLE, HOLE, 

/* 96 */ HOLE, HOLE, c(’ ’), HOLE, HOLE, HOLE, HOLE, HOLE, 

/*104 */ HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, 

/*112*/ HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, 

/ *120*1 HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, HOLE, IDLE, 

}; 


/* "Key Up" keyboard table for "VT100 style" */ 


static struct keymap keytab vt up = { 

/* 0*/ HOLE, BUCKYBITS+SYSTEMBIT, 






HOLE, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 

/* 8 */ 

HOLE, 

HOLE, 

NOP, 

NOP, 

NOP, 

NOP, 

HOLE, 

OOPS, 


/* 16 *1 

OOPS, 

OOPS, 

OOPS, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 


/* 24 */ 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 


/* 32 */ 

NOP, 

NOP, 

BUCKYBITS+METABIT, 









NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

/* 40 *1 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 


/* 48 *1 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 


/* 56 */ 

NOP, 

SHEFTKE Y S +LEFTCTRL, 









SHIFTKEYS+CAPSLOCK, 








NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

/* 64 *1 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 


/* 72 */ 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

SHIFTKEYS+LEFTSHIFT, 









NOP, 

NOP, 

/* 80 */ 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 


/* 88 */ 

SHIFTKEYS+RIGHTSHIFT, 









NOP, 

NOP, 

HOLE, 

NOP, 

NOP, 

HOLE, 

HOLE, 

/* 96 */ 

HOLE, 

HOLE, 

NOP, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 


/*104 */ 

HOLE, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 


/*112 */ 

HOLE, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 


/*120 */ 

HOLE, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 

RESET, 



}; 


/* Index to keymaps for "VT100 style" keyboard */ 
static struct keyboard keyindexvt = { 
&keytab_vt_lc, 

&keytab_vt_uc, 
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&keytab_vt_cl, 

&keytab_vt_ct, 

&keytab_vt_up, 

CAPSMASK+CTLSMASK, /* Shift keys that stay on at idle keyboard */ 
0x0000, /* Bucky bits that stay on at idle keyboard *1 

1, 59, /* abort keys */ 

0x0000, /* Shift bits which toggle on down event */ 


/* Unshifted keyboard table for Sun-3 keyboard */ 


static struct 
/* 0 */ 


/* 8 */ 
/* 16 */ 
/* 24 */ 
/* 32 */ 
/* 40 */ 
/* 48 */ 
/* 56 */ 
/* 64 */ 


/* 72 */ 

/* 80 */ 
/* 88 */ 


/* 96 */ 
/*104 */ 
/*112 */ 
1 * 120*1 


}; 


keymap keytab_s3_lc = { 


HOLE, 

BUCKYBITS+SYSTEMBIT, 







HOLE, 

LF(2), HOLE, 

TF(1), 

TF(2), 

HOLE, 

TF(3), 

HOLE, 

TF(4), 

HOLE, 

TF(5), HOLE, 

TF(6), 

HOLE, 


TF(7), 

TF(8), 

TF(9), 

ALT, 

HOLE, RF(1), 

RF(2), 

RF(3), 


HOLE, 

LF(3), 

LF(4), 

HOLE, 

HOLE, c(’[’)» 

’1’, 

’2’, 


’3’, 

’4’, 

’5’, 

’6’, 

’7’, ’8’, 

’9’, 

’O’, 


9 9 

9 

9 _9 
~ 9 

919 

9 

’\b’, 

HOLE, RF(4), 

RF(5), 

RF(6), 


HOLE, 

LF(5), 

HOLE, 

LF(6), 

HOLE, ’\t’, 

’q’. 

’w’, 


’e\ 

’r’, 


’y’» 

’u’, T, 

’o’, 

>_> 

P . 


T, 


0x7F, 

HOLE, 

RF(7), STRING+UPARROW, 








RF(9), 

HOLE, 

LF(7), 

LF(8), 

LF(14), 

HOLE, 

SHEFTKEYS+LEFTCTRL, 







’a’. 

’s’, 

’d\ 

T, 

’g’, 

’h’, 

’j’. 

’k’, ’1’, 

J 9 



’W, 

’\r’, 

HOLE, 

STRING+LEFT ARROW, 








RF(ll), 

STRING+RIGHTARROW, 







HOLE, 

LF(9), 

LF(15), 

LF(10), 

HOLE, 

SHEFTKEYS+LEFTSHIFT, 







’z’, 

’x’, 

’c’, 

’v’, 

’b’. 

’n’, 

’m\ 

9 9 

9 9 

9 9 9 19 

•9 >9 

SHIFTKEYS+RIGHTSHIFT, 


’\n’. 


RF(13), STRING+DOWN ARROW, 

RF(15), HOLE, HOLE, HOLE, HOLE, SHIFTKEYS+CAPSLOCK, 
BUCKYBITS+METABIT, 

’ ’, BUCKYBITS+METABIT, 

HOLE, HOLE, HOLE, ERROR, IDLE, 


/* Shifted keyboard table for Sun-3 keyboard *1 


static struct keymap keytab_s3_uc = { 


1* 0 *1 

HOLE, 

BUCKYBITS+SYSTEMBIT, 







HOLE, 

LF(2), HOLE, 

TF(1), 

TF(2), 

/* 8 */ 

TF(3), 

HOLE, 

TF(4), 

HOLE, 

TF(5), HOLE, 

TF(6), 

HOLE, 

1* 16 */ 

TF(7), 

TF(8), 

TF(9), 

ALT, 

HOLE, RF(1), 

RF(2), 

RF(3), 

/* 24 *t 

HOLE, 

LF(3), 

LF(4), 

HOLE, 

HOLE, c(’[’), 


/* 32 */ 

’#’, 



>AJ 

9 




/* 40 *1 

9 9 

9 


9-9 

9 

’\b’, 

HOLE, RF(4), 

RF(5), 

RF(6), 

/* 48 */ 

HOLE, 

LF(5), 

HOLE, 

LF(6), 

HOLE, ’\t’. 

’Q’, 

’W’, 

1* 56 */ 

’E’, 

’R’, 

’T’, 

’Y’, 

’U’, T, 

’O’, 

’P’, 

1* 64 */ 

T, 


0x7F, 

HOLE, 

RF(7), STRING+UPARROW, 
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/* 72 */ 

/* 80 */ 
/* 88 */ 

/* 96 */ 
/* 104 */ 
/*112 */ 
1 * 120*1 


}; 


RF(9), HOLE, 

LF(7), LF(8), HOLE, HOLE, SHIFTKEY S+LEFTCTRL, 

’A’, ’S’, ’D’, 

’F’, ’G’, ’H’, T, ’K’, ’L’, 

T, V, HOLE, STRING+LEFT ARROW, 

RF(ll), STRING+RIGHTARROW, 

HOLE, LF(9), 

LF(15), LF(10), HOLE, SHIFTKEYS+LEFTSHIFT, 

’Z’, ’X’, ’C\ ’V’, 

’B\ ’N’, ’M’, ’<’, ’>’, SHIFTKEYS+RIGHTSHIFT, 

’\n’, 


RF(13), STRING+DOWN ARROW, 

RF(15), HOLE, HOLE, HOLE, HOLE, SHIFTKEYS+CAPSLOCK, 
BUCKYBITS+METABIT, 

’ ’, BUCKYBITS+METABIT, 

HOLE, HOLE, HOLE, ERROR, IDLE, 


/* Caps Locked keyboard table for Sun-3 keyboard */ 


static struct keymap keytab_s3_cl = { 


/* o */ 

HOLE, 

BUCKYBITS+SYSTEMBIT, 









HOLE, 

LF(2), 

HOLE, 

TF(1), 

TF(2), 

HOLE, 

/* 8*/ 

TF(3), 

HOLE, 

TF(4), 

HOLE, 

TF(5), 

HOLE, 

TF(6), 

HOLE, 


/* 16 */ 

TF(7), 

TF(8), 

TF(9), 

ALT, 

HOLE, 

RF(1), 

RF(2), 

RF(3), 


/* 24 */ 

HOLE, 

LF(3), 

LF(4), 

HOLE, 

HOLE, 

c(’[’), 

’1’, 

’2’, 


/* 32 */ 

’3’, 

’4’, 

’5’, 

’6’, 

’7’, 

’8’, 

’9’, 

’O’, 


/* 40 */ 

9 3 

3 

3 3 

9 

3 

’\b\ 

HOLE, 

RF(4), 

RF(5), 

RF(6), 


/* 48 */ 

HOLE, 

LF(5), 

HOLE, 

LF(6), 

HOLE, 

’\t’, 

’Q’, 

’W’, 


/* 56 */ 

’E’, 

’R’, 

’T’, 

*Y’, 

’U’, 

’I’, 

’O’, 

’P’, 


/* 64 */ 


T, 

0x7F, 

HOLE, 

RF(7), 

STRING+UPARROW, 










RF(9), 

HOLE, 

/* 72 *1 

LF(7), 

LF(8), 

HOLE, 

HOLE, 

SHIFTKEYS+LEFTCTRL, 









’A’, 

’S’, 

’D’, 

/* 80 */ 

’F’, 

’G\ 

’H’, 

’J’, 

’K’, 

’L’, 

3.3 

9 3 



/* 88 */ 

’W\ 

’V, 

HOLE, 

STRING+LEFT ARROW, 





RF(ll), STRING+RIGHTARROW, 
HOLE, LF(9), 

/* 96 */ LF(15), LF(10), HOLE, SHIFTKEYS+LEFTSHIFT, 

’Z’, ’X’, ’C’, ’V’, 

/*104 */ ’B\ ’N’, ’M’, ’/’, SHIFTKEYS+RIGHTSHIFT, 

’\n\ 


/*112 */ RF(13), STRING+DOWNARROW, 

RF(15), HOLE, HOLE, HOLE, HOLE, SHIFTKEYS+CAPSLOCK, 
/*120 */ BUCKYBITS+METABIT, 

’ ’, BUCKYBITS+METABIT, 

HOLE, HOLE, HOLE, ERROR, IDLE, 


}; 


/* Controlled keyboard table for Sun-3 keyboard *1 
static struct keymap keytab_s3_ct = { 
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/* 0 */ 

/* 8 *1 
/* 16 *1 
/* 24 *1 
/* 32 */ 
/* 40 */ 
I* 48 */ 
I* 56 */ 
1*64*1 

/* 72 */ 

/* 80 *1 
/* 88 */ 


/* 96 */ 
/*104 */ 
/*112 */ 
1 * 120*1 


}; 


/* "Key Up" 

static struct 
/* 0 */ 

/* 8 */ 

/* 16 */ 

/* 24 */ 

I* 32 */ 

/* 40 */ 

/* 48 */ 

/* 56 */ 
1*64*1 
I* 72 */ 

/* 80 */ 

I* 88 */ 

I* 96 */ 

/*104 */ 

/*112 */ 


FILE FORMATS 


HOLE, 

BUCKYBITS+SYSTEMBIT, 



TF(3), 

HOLE, 

TF(4), 

HOLE, 

HOLE, 

LF(2), HOLE, TF(1), 
TF(5), HOLE, TF(6), 

TF(2), 

HOLE, 

HOLE, 

TF(7), 

TF(8), 

TF(9), 

ALT, 

HOLE, RF(1), RF(2), 

RF(3), 


HOLE, 

LF(3), 

LF(4), 

HOLE, 

HOLE, c(T), ’1’, 

c(’@’), 


’3’, 

’4’, 

’5’, 

cr), 

’7’, ’8’, ’9’, 

’O’, 


c 

>_> 

> 

cr’>, 

’\b’. 

HOLE, RF(4), RF(5), 

RF(6), 


HOLE, 

LF(5), 

HOLE, 

LF(6), 

HOLE, ’\t’, c(’q’). 

c(’w’), 


c(’e’), 

c(’r’), 

c(’t’). 

c(’y’)> 

c(’u’), c(’i’), c(’o’), 

c(’p’), 


c(T)» 

c (’]’), 

0x7F, 

HOLE, 

RF(7), STRING+UP ARROW, 


LF(7), 

LF(8), 

HOLE, 

HOLE, 

RF(9), 

SHIFTKEY S +LEFTCTRL, 

HOLE, 

c(T), 

c(’g’), 

c(’h’). 

c(’j’), 

c(’a’), 

c(’k’), c(T), 

c(’s’), 

c(’d’), 

c(’\\’). 


V, 

HOLE, 

STRING+LEFT ARROW, 




RF(ll), STRING+RIGHTARROW, 
HOLE, LF(9), 

LF(15), LF(10), hole, shiftkeys+leftshift, 


c(’z’), c(’x’), c(’c’), c(’v’), 

c(’b’), c(’n’), c(’m’), c(’_’), SHIFTKEYS+RIGHTSHEFT, 

’\n’, 


RF(13), STRING+DOWN ARROW, 

RF(15), HOLE, HOLE, HOLE, HOLE, SHIFTKEYS+CAPSLOCK, 
BUCKYBITS+METABIT, 


c(’ ’), BUCKYBITS+METABIT, 

HOLE, HOLE, HOLE, ERROR, IDLE, 


keyboard table for Sun-3 keyboard */ 


keymap keytab_s3_up = { 


HOLE, 

BUCKYBITS+SYSTEMBIT, 








HOLE, 

OOPS, 

HOLE, 

OOPS, 

OOPS, 

HOLE, 

OOPS, 

HOLE, 

OOPS, 

HOLE, 

OOPS, 

HOLE, 

OOPS, 

HOLE, 

OOPS, 

OOPS, 

OOPS, 

OOPS, 

HOLE, 

OOPS, 

OOPS, 

NOP, 


HOLE, 

OOPS, 

OOPS, 

HOLE, 

HOLE, 

NOP, 

NOP, 

NOP, 


NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 


NOP, 

NOP, 

NOP, 

NOP, 

HOLE, 

OOPS, 

OOPS, 

NOP, 


HOLE, 

OOPS, 

HOLE, 

OOPS, 

HOLE, 

NOP, 

NOP, 

NOP, 


NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 


NOP, 

NOP, 

NOP, 

HOLE, 

OOPS, 

OOPS, 

NOP, 

HOLE, 


OOPS, 

OOPS, 

HOLE, 

HOLE, 

SHIFTKEY S +LEFTCTRL, 








NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 


NOP, 

NOP, 

HOLE, 

OOPS, 

OOPS, 

NOP, 

HOLE, 

OOPS, 


OOPS, 

OOPS, 

HOLE, 

SHIFTKEYS+LEFTSHIFT, 








NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

NOP, 

SHIFTKEYS+RIGHTSHIFT, 









NOP, 

OOPS, 

OOPS, 

NOP, 

HOLE, 

HOLE, 

HOLE, 

HOLE, 

NOP, 
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/*120 */ 


}; 


BUCKYBITS+METABIT, 

NOP, BUCKYBITS+METABIT, 

HOLE, HOLE, HOLE, HOLE, RESET, 


/* Index to keymaps for Sun-3 keyboard */ 
static struct keyboard keyindex_s3 = { 
&keytab_s3_lc, 
&keytab_s3_uc, 
&keytab_s3_cl, 
&keytab_s3_ct, 
&keytab_s3_up, 

0x0000, 

0x0000, 

1, 77, 

CAPSMASK, 


/* Shift bits which stay on with idle keyboard *1 
/* Bucky bits which stay on with idle keyboard */ 
/* abort keys */ 

/* Shift bits which toggle on down event */ 


}; 


l^^^^^^t********************************************************************/ 

/* Index table for the whole shebang */ 

/«*:(;***************£********************************************************/ 

int nkeytables = 4; /* max 16 */ 

struct keyboard *keytablesQ = { 

&keyindex_ms, 

&keyindex_vt, 

&keyindex_s2, 

&keyindex_s3, 

}; 

/* 

Keyboard String Table 

This defines the strings sent by various keys (as selected in the 
tables above). 

The first byte of each string is its length, the rest is data. 

*1 

#define kstescinit(c) {’\033\ ’[’, ’c’, ’\0’} 
char keystringtab[16][KTAB_STRLEN] = { 
kstescinit(H) /*home*/, 
kstescinit(A) /*up*/, 
kstescinit(B) /*down*/, 
kstescinit(D) /*left*/, 
kstescinit(C) /*right*/, 

}; 
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NAME 

mntent - static information about filesystems 
SYNOPSIS 

#inc!ude <mntent.h> 

DESCRIPTION 

The file letdfstab describes the file systems and swapping partitions used by the local machine. It is 
created by the system administrator using a text editor and processed by commands which mount, 
unmount, check consistency of, dump and restore file systems, and by the system in providing swap space. 

It consists of a number of lines of the form: 

fsname dir type opts freq passno 

an example of which would be: 

/dev/xyOa / 4.2 rw, noquota 1 2 

The entries from this file are accessed using the routines in getmntent(3), which returns a structure of the 
following form: 

struct mntent { 

char *mnt_fsname; I* file system name */ 

char *mnt_dir; /* file system path prefix */ 

char *mnt_type; /* 4.2, nfs, swap, or ignore */ 

char *mnt_opts; /* ro, quota, etc. */ 

int mnt freq; /* dump frequency, in days */ 

int mnt_passno; /* pass number on parallel fsck */ 

}; 

The fields are separated by white space, and a ’#’ as the first non-white character indicates a comment. 

The mnt type field determines how the mnt Jsname, and mnt opts fields will be interpreted. Below is a list 
of the file system types currently supported and the way each of them interprets these fields. 

4.2 

mntfsname Must be a block special device, 
mnt opts Valid opts are ro, rw, quota, noquota. 

NFS 

mnt fsname The path on the server of the directory to be served, 
mnt opts Valid opts are ro, rw, quota, noquota, hard, soft. 

SWAP 

mnt_fsname Must be a block special device swap partition, 
mntopts Ignored. 

If the mntjype is specified as “ignore” the entry is ignored. This is useful to show disk partitions which 
are currently not used. 

The field mnt Jreq indicates how often each partition should be dumped by the dump (8) command (and 
triggers that commands w option which tells which file systems should be dumped). Most systems set the 
mnt Jreq field to 1 indicating that the file systems are dumped each day. 

The final field mnt _passno is used by the disk consistency check program fsck (8) to allow overlapped 
checking of file systems during a reboot. All file systems with mnt _passno of 1 are first checked simul- 
taneosly, then all file systems with mnt _passno of 2, and so on. It is usual to make the mnt jpassno of the 
root file system have the value 1 and then check one file system on each available disk drive in each subse- 
quent pass to the exhaustion of file system partitions. 
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/etc/fstab is only read by programs, and not written; it is the duty of the system administrator to properly 
create and maintain this file. The order of records in letclfstab is important because fsck, mount, and 
amount process the file sequentially; file systems must appear after file systems they are mounted within. 

FILES 

/etc/fstab 
SEE ALSO 

fsck(8), getmntent(3), mount(8), quotacheck(8), quotaon(8), umount(8) 
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1985" 

NAME 

mtab — mounted file system table 

SYNOPSIS 

#include <fstab.h> 

DESCRIPTION 

Mtab resides in the I etc directory, and contains a table of devices mounted by the mount command. 
Umount removes entries. 

The table is a set of mount entries, one per line, as defined in <fstab.h>. The type field indicates which 
type of file system (4.2, nfs, swap, etc.) is mounted, and the options field tells if the file system is mounted 
read-only, read-write, or read-write with disk quotas enabled. 

This table is present only so people and programs can look at it It does not matter to mount if there are 
duplicated entries nor to umount if a name cannot be found. 

FILES 

/etc/mtab 

SEE ALSO 

mount(8) fstab(5) 
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NAME 

netgroup - list of network groups 
DESCRIPTION 

Netgroup defines network wide groups, used for permission checking when doing remote mounts, remote 
logins, and remote shells. For remote mounts, the information in netgroup is used to classify machines; for 
remote logins and remote shells, it is used to classify users. Each line of the netgroup file defines a group 
and has the format 

groupname memberl member2 .... 

where member/ is either another group name, or a triple: 

(hostname, username, domainname) 

Any of three fields can be empty, in which case it signifies a wild card. Thus 
universal („) 

defines a group to which everyone belongs. Field names that begin with something other than a letter, digit 
or underscore (such as work in precisely the opposite fashion. For example, consider the following 
entries: 

justmachines (analytica,-,sun) 
justpeople (-,babbage,sun) 

The machine analytica belongs to the group justmachines in the domain sun, but no users belong to it. 
Similarly, the user babbage belongs to the group justpeople in the domain sun, but no machines belong to 
it. 

Network groups are contained in the yellow pages, and are accessed through these files: 

/etc/yp/domainname/netgroup.dir 

letc/yp/domainnamelnetgcoup.pag 

/etc/yp/d<?ffwm/iam«/netgroup.byuser.dir 

/etc/yp/doffia/nnawe/netgroup.byuser.pag 

/etc/yp/do/nai/inam^/netgroup.byhosLdir 

/etc/yp/(io/na/nname/netgroup.byhost.pag 

These files can be created from letc/netgroup using makedbm(S). 

FILES 

/etc/netgroup 

I eiclypl domainnamelnetgroup.dk 

/ etc/yp/domainname/netgroup.pag 

/etdyp/domainname/netgroup.byuser.dii 

/etdyp/domainname/netgroup.byuseT.png 

/etdyp/domainname/netgroup.byhost.dir 

/etdyp/domainname/netgroup.byhost.p&g 

SEE ALSO 

getnetgrent(3), exportfs(8), makedbm(8), ypserv(8) 
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NAME 

netrc - .netrc file for berknet information 
DESCRIPTION 

The .netrc file contains frequently-needed options for newtork commands. 

The format of the .netrc file is as follows: Each line of the .netrc file defines options for a specific machine. 
A line in the .netrc file can be either a machine line or a default line. The default line must be the first 
line in the .netrc file if it is present. Lines thus appear as: 
default default machine name 
machine machine name options 

Fields on each line are separated by spaces or tabs. 

The options for a machine line are: 


Option 

Parameter 

Default 

Description 

login 

name 

localname 

login name for remote machine 

password 

password 

(none) 

password for remote login name 

command 

command 

(none) 

default command to be executed 

write 

yes/no 

yes 

write to user if possible 

force 

yes/no 

no 

always prompt for login name and password 

quiet 

yes/no 

no 

Hike the -q option 
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NAME 

networks - network name data base 
DESCRIPTION 

The networks file contains information regarding the known networks which comprise the DARPA Inter- 
net. For each network a single line should be present with the following information: 

official network name 
network number 
aliases 

Items are separated by any number of blanks and/or tab characters. A “#” indicates the beginning of a 
comment; characters up to the end of the line are not interpreted by routines which search the file. This file 
is normally created from the official network data base maintained at the Network Information Control 
Center (NIC), though local changes may be required to bring it up to date regarding unofficial aliases 
and/or unknown networks. 

Network number may be specified in the conventional notation using the inetnetworkQ routine from 
the Internet address manipulation library, frier (3N). Network names may contain any printable character 
other than a field delimiter, newline, or comment character. 

FILES 

/etc/networks 

SEE ALSO 

getnetent(3N) 

BUGS 

A name server should be used instead of a static file. A binary indexed file format should be available for 
fast access. 
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NAME 

news - USENET network news article, utility files 
DESCRIPTION 

There are two formats of news articles: A and B, A format is the only format that version 1 netnews sys- 
tems can read or write. Systems running the version 2 netnews can read either format and there are provi- 
sions for the version 2 netnews to write in A format. A format looks like this: 

Aarticle-ID 

newsgroups 

path 

date 

title 

Body of article 


Only version 2 netnews systems can read and write B format. B format contains two extra pieces of infor- 
mation: receival date and expiration date. The basic structure of a B format file consists of a series of 
headers and then the body. A header field is defined as a line with a capital letter in the 1st column and a 
colon somewhere on the line. Unrecognized header fields are ignored. News is stored in the same format 
transmitted, see “Standard for the Interchange of USENET Messages” for a full description. The follow- 
ing fields are among those recognized: 

Header Information 


From: 

Newsgroups: 

Message-ID: 

Subject: 

Date: 


user@ host. domain[. domain ...] (Full Name) 

Newsgroups 

<Unique Identifier > 

descriptive title 

Date Posted 


Date-Received: 

Expires: 

Reply-To: 

References: 

Control: 


Date received on local machine 
Expiration Date 
Address for mail replies 
Article ID of article this is 
Text of a control message 


Here is an example of an article: 


Relay-Version: B 2.10 2/13/83 cbosgd.UUCP 

Posting-Version: B 2.10 2/13/83 eagle.UUCP 
Path: cbosgd!mhuxj!mhuxt!eagle!jerry 
From: jerry@eagle.uucp (Jerry Schwarz) 
Newsgroups: net.general 
Subject: Usenet Etiquette - Please Read 
Message-ID: <642@eagle.UUCP> 

Date: Friday, 19-Nov-82 16:14:55 EST 
Followup-To: net.news 
Expires: Saturday, l-Jan-83 00:00:00 EST 
Date-Received: Friday, 19-Nov-82 16:59:30 EST 
Organization: Bell Labs, Murray Hill 


The body of the article comes here, after a blank line. 
A sys file line has four fields, each seperated by colons: 


408 


Last change: 6 January 1984 


Sun Release 3.0 



NEWS ( 5 ) 


FILE FORMATS 


NEWS (5) 


system-name:subscriptions:flags:transmission command 

Of these fields, on the system-name and subscriptions need to be present 

The system name is the name of the system being sent to. The subscriptions is the list of newsgroups to be 
transmitted to the system. The flags are a set of letters describing how the article should be transmitted. 
The default is B. Valid flags include A (send in A format), B (send in B format), N (use ihave/sendme pro- 
tocol), U (use uux -c and the name of the stored article in a %s string). 

The transmission command is executed by the shell with the article to be transmitted as the standard input. 
The default is uux — z-r sysname Irnews. Some examples: 

xyz:net.all 

oldsys:net.all,fa.aIl,to.oIdsys:A 

berksys:net.all,ucb.all::/usr/lib/news/sendnews -b berksys:rnews 
arpasys:net.all,arpa.all::/usi7lib/news/sendnews -a rnews@arpasys 
old2:net.all,fa.all:A:/usr/lib/sendnews -o old2:rnews 
user:fa.sf-lovers::mail user 

Somewhere in a sys file, there must be a line for the host system. This line has no flags or commands. A # 
as the first character in a line denotes a comment 

The history, active, and ngfile files have one line per item. 

SEE ALSO 

inews(l), postnews(l), sendnews(8), uurec(8), readnews(l) 
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NAME 

newsrc - information file for readnews and checknews 
DESCRIPTION 

The .newsrc file contains the list of previously read articles and an optional options line for readnews { 1) 
and checknews {\). Each newsgroup that articles have been read from has a line of the form: 

newsgroup : range 

Range is a list of the articles read. It is basically a list of numbers separated by commas with sequential 
numbers collapsed with hyphens. For instance: 
general: 1-78,80,85-90 
fa.info-cpm: 1-7 
netinews: 1 
fa.info-vax! 1-5 

If the : is replaced with an ! (as in info-vax above) the newsgroup is not subscribed to and is not be shown 
to the user. 

An options line starts with the word options (left-justified). Then there are the list of options just as they 
would be on the command line. For instance: 

options -n all !fa.sf-lovers !fa. human-nets -r 
options -c -r 

A string of lines beginning with a space or tab after the initial options line are considered continuation 
lines. 

FILES 

'/.newsrc options and list of previously read articles 

SEE ALSO 

readnews(l), checknews(l) 
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NAME 

passwd - password file 

SYNOPSIS 

/etc/passwd 

DESCRIPTION 

The passwd file contains for each user the following information: 

name User’s login name — contains no upper case characters and must not be greater than eight 
characters long. 

password encrypted password 
numerical user ID 

This is the user’s ID in the system and it must be unique, 
numerical group ID 

This is the number of the group that the user belongs to. 
user’s real name 

In some versions of UNIX, this field also contains the user’s office, extension, home phone, 
and so on. For historical reasons this field is called the GCOS field. 

initial working directory 

The directory that the user is positioned in when they log in — this is known as the ‘home’ 
directory. 

shell program to use as Shell when the user logs in. 

The user’s real name field may contain *&’, meaning insert the login name. 

The password file is an ASCII file. Each field within each user’s entry is separated from the next by a 
colon. Each user is separated from the next by a new-line. If the password field is null, no password is 
demanded; if the Shell field is null, /bin/sh is used. 

The passwd file can also have line beginning with a plus (+), which means to incorporate entries from the 
yellow pages. There are three styles of + entries: all by itself, + means to insert the entire contents of the 
yellow pages password file at that point; +name means to insert the entry (if any) for name from the yellow 
pages at that point; +@name means to insert the entries for all members of the network group name at that 
point. If a + entry has a non-null password, directory, gecos, or shell field, they will overide what is con- 
tained in the yellow pages. The numerical user ID and group ID fields cannot be overridden. 

EXAMPLE 

Here is a sample letclpasswd file: 


root :q.mJzTnu8icF . : 0 : 10 :God: / : /bin/csh 

tut : 6k/7KCFRPNVXg : 508 : 10 : Bill Tuthill : /usr2/tut : /bin/csh 
+ john: 

+@document at ion : no-login : 

+ : : : Guest 

In this example, there are specific entries for users root tut, in case the yellow pages are out of order. The 
user will have his password entry in the yellow pages incorporated without change; anyone in the netgroup 
documentation will have their password field disabled, and anyone else will be able to log in with their 
usual password, shell, and home directory, but with a gecos field of Guest. 

The password file resides in the /etc directory. Because of the encrypted passwords, it has general read 
permission and can be used, for example, to map numerical user ED’s to names. 

Appropriate precautions must be taken to lock the letclpasswd file against simultaneous changes if it is to 
be edited with a text editor; vipw{%) does the necessary locking. 
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FILES 

/etc/passwd 
SEE ALSO 

getpwent(3), login(l), crypt(3), passwd(l), group(5), vipw(8), adduser(8) 
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NAME 

phones - remote host phone number data base 

SYNOPSIS 

/etc/phones 

DESCRIPTION 

The file letclphones contains the system-wide private phone numbers for the tip( 1C) program, letclphones 
is normally unreadable, and so may contain privileged information. The format of letclphones is a series of 
lines of the form: <system-name>[ \t] * <phone-number>. The system name is one of those defined in the 
remote (5) file and the phone number is constructed from [0123456789-=*%]. The '=’ and '*’ characters 
are indicators to the auto call units to pause and wait for a second dial tone (when going through an 
exchange). The '=’ is required by the DF02-AC and the “*’ is required by the BIZCOMP 1030. 

Comment lines are lines containing a *#’ sign in the first column of the line. 

Only one phone number per line is permitted. However, if more than one line in the file contains the same 
system name tip( 1C) will attempt to dial each one in turn, until it establishes a connection. 

FILES 

/etc/phones 

SEE ALSO 

tip(lC), remote(5) 
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NAME 

plot - graphics interface 
DESCRIPTION 

Files of this format are produced by routines described in plot(?>X), and are interpreted for various devices 
by commands described in plot( 1G). A graphics file is a stream of plotting instructions. Each instruction 
consists of an ASCII letter usually followed by bytes of binary information. The instructions are executed 
in order. A point is designated by four bytes representing the x and y values; each value is a signed integer. 
The last designated point in an 1, m, n, or p instruction becomes the ‘current point’ for the next instruction. 

Each of the following descriptions begins with the name of the corresponding routine in plot{ 3X). 
m move: The next four bytes give a new current point 

n cont: Draw a line from the current point to the point given by the next four bytes. See plot ( 1G). 
p point: Plot the point given by the next four bytes. 

I line: Draw a line from the point given by the next four bytes to the point given by the following four 
bytes. 

t label: Place the following ASCII string so that its first character falls on the current point The string is 
terminated by a newline. 

a arc: The first four bytes give the center, the next four give the starting point and the last four give the 
end point of a circular arc. The least significant coordinate of the end point is used only to determine 
the quadrant. The arc is drawn counter-clockwise. 

c circle: The first four bytes give the center of the circle, the next two the radius, 
e erase: Start another frame of output. 

f linemod: Take the following string, up to a newline, as the style for drawing further lines. The styles 
are ‘dotted,’ ‘solid,’ ‘longdashed,’ ‘shortdashed,’ and ‘dotdashed.’ Effective only in plot 4014 and plot 
ver. 

s space: The next four bytes give the lower left comer of the plotting area; the following four give the 
upper right comer. The plot will be magnified or reduced to fit the device as closely as possible. 

Space settings that exacdy fill the plotting area with unity scaling appear below for devices supported 
by the filters of plot (IG). The upper limit is just outside the plotting area. In every case the plotting 
area is taken to be square; points outside may be displayable on devices whose face isn’t square. 

4014 space(0, 0, 3120, 3 120); 

ver space(0, 0, 2048, 2048); 

300, 300s space(0, 0, 4096, 4096); 

450 space(0, 0, 4096, 4096); 

SEE ALSO 

plot(lG), plot(3X), graph(lG) 
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NAME 

printcap - printer capability data base 

SYNOPSIS 

/etc/printcap 

DESCRIPTION 

Printcap is a simplified version of the termcap(5) data base for describing printers. The spooling system 
accesses the printcap file every time it is used, allowing dynamic addition and deletion of printers. Each 
entry in the data base describes one printer. This data base may not be substituted for, as is possible for 
termcap, because it may allow accounting to be bypassed. 

The default printer is normally Ip, though the environment variable PRINTER may be used to override this. 
Each spooling utility supports a -P printer option to explicitly name a destination printer. 

Refer to the Line Printer Spooler Manual in the Sun System Administration Manual for a discussion of how 
to set up the database for a given printer. 

Each entry in the printcap file describes a printer, and is a line consisting of a number of fields separated by 
characters. The first entry for each printer gives the names which are known for the printer, separated 
by T characters. The first name is conventionally a number. The second name given is the most common 
abbreviation for the printer, and the last name given should be a long name fully identifying the printer. 
The second name should contain no blanks; the last name may well contain blanks for readability. Entries 
may continue onto multiple lines by giving a \ as the last character of a line, and empty fields may be 
included for readability. 

Capabilities in printcap are all introduced by two-character codes, and are of three types: 

Boolean capabilities indicate that the printer has some particular feature. Boolean capabilities are sim- 
ply written between the *:’ characters, and are indicated by the word ‘bool’ in the type column 
of the capabilities table below. 

Numeric capabilities supply information such as baud-rates, number of lines per page, and so on. 

Numeric capabilities are indicated by the word ‘num’ in the type column of the capabilities 
table below. Numeric capabilities are given by the two-character capability code followed by 
the ‘#’ character, followed by the numeric value. For example: :br#1200: is a numeric entry 
stating that this printer should run at 1200 baud. 

String capabilities give a sequence which can be used to perform particular printer operations such as 
cursor motion. String valued capabilities are indicated by the word ‘str’ in the type column of 
the capabilities table below. String valued capabilities are given by the two-character capabil- 
ity code followed by an *=’ sign and then a string ending at the next following For exam- 
ple, :rp=spinwriter: is a sample entry stating that the remote printer is named ‘spinwriter’. 


CAPABILITIES 

Name 

Type 

Default 

Description 

af 

str 

NULL 

name of accounting file 

br 

num 

none 

if lp is a tty, set the baud rate (ioctl call) 

cf 

str 

NULL 

cifjplot data filter 

df 

str 

NULL 

TeX data filter (DVI format) 

du 

str 

0 

User ID of user ‘daemon’. 

fc 

num 

0 

if lp is a tty, clear flag bits (sgtty.h) 

ff 

str 

“\ f , 

string to send for a form feed 

fo 

bool 

false 

print a form feed when device is opened 

fs 

num 

0 

like ‘fc’ but set bits 

gf 

str 

NULL 

graph data filter (plot (3X) format) 

ic 

bool 

false 

driver supports (non standard) ioctl 

if 

str 

NULL 

call for indenting printout 

name of text filter which does accounting 
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If 

str 

“/dev/console" 

error logging file name 

lo 

str 

“lock" 

name of lock file 

Ip 

str 

“/dev/lp" 

device name to open for output 

me 

num 

0 

maximum number of copies 

mx 

num 

1000 

maximum file size (in BUFSIZ blocks), zero = unlimited 

nd 

str 

NULL 

next directory for list of queues (unimplemented) 

nf 

str 

NULL 

ditroff data filter (device independent troff) 

of 

str 

NULL 

name of output filtering program 

pl 

num 

66 

page length (in lines) 

pw 

num 

132 

page width (in characters) 

px 

num 

0 

page width in pixels (horizontal) 

py 

num 

0 

page length in pixels (vertical) 

rf 

str 

NULL 

filter for printing FORTRAN style text files 

rm 

str 

NULL 

machine name for remote printer 

rp 

str 

"lp" 

remote printer name argument 

rs 

bool 

false 

restrict remote users to those with local accounts 

rw 

bool 

false 

open printer device read/write instead of read-only 

sb 

bool 

false 

short banner (one line only) 

sc 

bool 

false 

suppress multiple copies 

sd 

str 

“/usr/spool/lpd" 

spool directory 

sf 

bool 

false 

suppress form feeds 

sh 

bool 

false 

suppress printing of burst page header 

St 

str 

“status" 

status file name 

tf 

str 

NULL 

troff data filter (cat phototypesetter) 

tr 

str 

NULL 

trailer string to print when queue empties 

vf 

str 

NULL 

raster image filter 

xc 

num 

0 

if lp is a tty, clear local mode bits (tty (4)) 

xs 

num 

0 

like ‘xc’ but set bits 


Error messages sent to the console have a carriage return and a line feed appended to them, rather than just 
a line feed. 

If the local line printer driver supports indentation, the daemon must understand how to invoke it. 

Note that the ‘fs’, ‘fc\ ‘xs’, and ‘xc’ fields are flag masks rather than flag values. Certain default device 
flags are set when the device is opened by the lineprinter daemon if the device is a tty. The flags indicated 
in the ‘fc’ field are then cleared; die flags in the ‘fs’ field are then set (or vice-versa, depending on the order 
of ‘fc#nnnn’ and ‘fs#nnnn’ in the /etc/printcap file). For example, to set exacdy the flags 06300 in the ‘fs’ 
field, do: 

:fc#0 177777 :fs#06300: 

The same process applies to die ‘xc’ and ‘xs’ fields. 

SEE ALSO 

termcap(5), lpc(8), lpd(8), pac(8), lpr(l), lpq(l), lprm(l) 

The Line Printer Spooler Manual in the Sun System Administration Manual . 
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NAME 

protocols - protocol name data base 

SYNOPSIS 

/etc/protocols 

DESCRIPTION 

The protocols file contains information regarding the known protocols used in the DARPA Internet. For 

each protocol a single line should be present with the following information: 

official protocol name 
protocol number 
aliases 

Items are separated by any number of blanks and/or tab characters. A “#” indicates the beginning of a 
comment; characters up to the end of the line are not interpreted by routines which search the file. 

Protocol names may contain any printable character other than a field delimiter, newline, or comment char- 
acter. 

EXAMPLE 

The following example is taken from the Sun UNIX system. 


FILES 


# 

# Internet (IP) protocols 

# 


ip 

0 

IP 

# internet protocol, pseudo protocol number 

icmp 

1 

ICMP 

# internet control message protocol 

ggP 

2 

GGP 

# gateway-gateway protocol 

top 

6 

TCP 

# transmission control protocol 

pup 

12 

PUP 

# PARC universal packet protocol 

udp 

17 

UDP 

# user datagram protocol 


/etc/protocols 


SEE ALSO 

getprotoent(3N) 


BUGS 

A name server should be used instead of a static file. A binary indexed file format should be available for 
fast access. 
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NAME 

rasterfile - Sun’s file format for raster images 
SYNOPSIS 

#include <rasterfile.h> 

DESCRIPTION 

A rasterfile is composed of three parts: first, a header containing 8 integers; second, a (possibly empty) set 
of colormap values; and third, the pixel image, stored a line at a time, in increasing y order. The image is 
layed out in the file as in a memory pixrect. Each line of the image is rounded up to the nearest 16 bits. 

The header is defined by the following structure: 

struct rasterfile { 


int 

ras_magic; 

int 

raswidth; 

int 

rasheight; 

int 

rasdepth; 

int 

raslength; 

int 

ras type; 

int 

rasmaptype; 

int 

rasmaplength; 


}; 

The ras magic field always contains the following constant: 

#define RAS MAGIC 0x59a66a95 

The ras width, ras height, and ras depth fields contain the image’s width and height in pixels, and its 
depth in bits per pixel, respectively. The depth is either 1 or 8, corresponding to standard frame buffer 
depths. The rasjength field contains the length in bytes of the image data. For an unencoded image, this 
number is computable from the rasjwidth, ras height, and rasdepth fields, but for an encoded image it 
must be explicitly stored in order to be available without decoding the image itself. Note that the length of 
the header and of the (possibly empty) colormap values are not included in the value of the rasjength 
field; it is only the image data length. For historical reasons, files of type RT OLD will usually have a 0 in 
the rasjength field, and software expecting to encounter such files should be prepared to compute the 
actual image data length if needed. The rasjnaptype and rasmaplength fields contain the type and length 
in bytes of the colormap values, respectively. If rasjnaptype is not RMTJfONE and the ras maplength is 
not 0, then the colormap values are the ras maplength bytes immediately after the header. These values 
are either uninterpreted bytes (usually with the rasjnaptype set to RMT RAW) or the equal length red, 
green and blue vectors, in that order (when the rasjnaptype is RMT_EQUAL_RGB ). In the latter case, the 
ras maplength must be three times the size in bytes of any one of the vectors. 

FILES 

/usr/include/rasterfile.h 
SEE ALSO 

Programmer’ s Reference Manual for SunWindows 
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NAME 

remote - remote host description file 

SYNOPSIS 

/etc/remote 

DESCRIPTION 

The systems known by rip(lC) and their attributes are stored in an ASCII file which is structured somewhat 
like the termcap(5) file. Each line in the file provides a description for a single system. Fields are 
separated by a colon Lines ending in a \ character with an immediately following newline are contin- 
ued on the next line. 

The first entry is the name(s) of the host system. If there is more than one name for a system, the names 
are separated by vertical bars. After the name of the system comes the fields of the description. A field 
name followed by an “=’ sign indicates a string value follows. A field name followed by a '#’ sign indi- 
cates a following numeric value. 

Entries named ‘tip*’ and ‘cu*’ are used as default entries by tip, and the cu interface to tip, as follows. 
When tip is invoked with only a phone number, it looks for an entry of the form ‘tip300’, where 300 is the 
baud rate with which the connection is to be made. When the cu interface is used, entries of the form 
‘cu300’ are used. 

CAPABILITIES 

Capabilities are either strings (str), numbers (num), or boolean flags (bool). A string capability is specified 
by capability =value ; for example, ‘dv=/dev/harris’. A numeric capability is specified by capability#value ; 
for example, ‘xa#99’. A boolean capability is specified by simply listing the capability. 

at (str) Auto call unit type. 

br (num) The baud rate used in establishing a connection to the remote host. This is a decimal 
number. The default baud rate is 300 baud. 

cm (str) An initial connection message to be sent to the remote host. For example, if a host is reached 
through port selector, this might be set to the appropriate sequence required to switch to the host. 

cu (str) Call unit if making a phone call. Default is the same as the ‘dv’ field, 

di (str) Disconnect message sent to the host when a disconnect is requested by the user, 

du (bool) This host is on a dial-up line. 

dv (str) UNIX device(s) to open to establish a connection. If this file refers to a terminal line, rip (1C) 
attempts to perform an exclusive open on the device to insure only one user at a time has access to 
the port. 

el (str) Characters marking an end-of-line. The default is NULL. Tip only recognizes ‘"’ escapes after 
one of the characters in ‘el’, or after a carriage-return. 

fs (str) Frame size for transfers. The default frame size is equal to BUFSIZ. 

hd (bool) The host uses half-duplex communication, local echo should be performed. 

ie (str) Input end-of-file marks. The default is NULL. 

oe (str) Output end-of-file string. The default is NULL. When tip is transferring a file, this string is 
sent at end-of-file. 

pa (str) The type of parity to use when sending data to the host. This may be one of ‘even’, ‘odd’, 
‘none’, ‘zero’ (always set bit 8 to zero), ‘one’ (always set bit 8 to 1). The default is ‘none’. 

pn (str) Telephone number(s) for this host. If the telephone number field contains an @ sign, tip 
searches the /etc /phones file for a list of telephone numbers — see phones (5). A % sign in the 
telephone number indicates a 5-second delay for the Ventel Modem. 

tc (str) Indicates that the list of capabilities is continued in the named description. This is used pri- 
marily to share common capability information. 
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Here is a short example showing the use of the capability continuation feature: 
UNIX-1200:\ 

:dv=/dev/cau0:el='D A lTCrS*Q A O@:du:at=ventel:ie=#$%:oe="D:br#1200: 

aipavax|ax:\ 

:pn=7654321%:tc=UNIX-1200 

FILES 

/etc/remote 

SEE ALSO 

tip(lC), phones(5) 
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NAME 

rmtab - remotely mounted file system table 
DESCRIPTION 

Rmtab resides in directory / etc and contains a record of all clients that have done remote mounts of file sys- 
tems from this machine. Whenever a remote mount is done, an entry is made in the rmtab file of the 
machine serving up that file system. Umount removes entries, if of a remotely mounted file system. 
Umount -a broadcasts to all servers, and informs them that they should remove all entries from rmtab 
created by the sender of the broadcast message. By placing a umount —a command in letc/rc.boot, rmtab 
tables can be purged of entries made by a crashed host, which upon rebooting did not remount the same file 
systems it had before. The table is a series of lines of the form 

hostname:directory 

This table is used only to preserve information between crashes, and is read only by mountd( 8) when it 
starts up. Mountd keeps an in-core table, which it uses to handle requests from programs like 
showmount{\) and shutdown (8). 

FILES 

/etc/rmtab 
SEE ALSO 

showmount(l), mountd(8), mount(8), umount(8), shutdown(8) 

BUGS 

Although the rmtab table is close to the truth, it is not always 100% accurate. 
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NAME 

rpc-rpc program number data base 

SYNOPSIS 

/etc/rpc 

DESCRIPTION 

The rpc file contains user readable names that can be used in place of rpc program numbers. Each line has 
the following information: 

name of server for the rpc program 

rpc program number 

aliases 

Items are separated by any number of blanks and/or tab characters. A “#” indicates the beginning of a 
comment; characters up to the end of the line are not interpreted by routines which search the file. 

Here is an example of the /etc/rpc file from the Sun UNIX System. 


# 



# 

# 

rpc 1.2 85/09/26 


TT 

rstatd 

100001 

rstat rup perimeter 

rusersd 

100002 

rusers 

nfs 

100003 

nfsprog 

ypserv 

100004 

ypprog 

mountd 

100005 

mount showmount 

ypbind 

100007 


walld 

100008 

rwall shutdown 

yppasswdd 

100009 yppasswd 


ethers tatd 

100010 etherstat 


rquotad 

100011 

rquotaprog quota rquota 

sprayd 

100012 

spray 

selectionsvc 

100014 selnsvc 


FILES 



/etc/rpc 



SEE ALSO 



getrpcent(3N) 
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NAME 

sccsfile - format of SCCS file 
DESCRIPTION 

An SCCS file is an ASCII file. It consists of six logical parts: the checksum, the delta table (contains infor- 
mation about each delta), user names (contains login names and/or numerical group IDs of users who may 
add deltas), flags (contains definitions of internal keywords), comments (contains arbitrary descriptive 
information about the file), and the body (contains the actual text lines intermixed with control lines). 

Throughout an SCCS file there are lines which begin with the ASCII SOH (start of heading) character (octal 
001). This character is hereafter referred to as the control character and will be represented graphically as 
@. Any line described below which is not depicted as beginning with the control character is prevented 
from beginning with the control character. 

Entries of the form DDDDD represent a five digit string (a number between 00000 and 99999). 

Each logical part of an SCCS file is described in detail below. 

Checksum 

The checksum is the first line of an SCCS file. The form of the line is: 

@hDDDDD 

The value of the checksum is the sum of all characters, except those of the first line. The @h pro- 
vides a magic number of (octal) 064001. 

Delta table 

The delta table consists of a variable number of entries of the form: 

@S DDDDD/DDDDD/DDDDD 

@d <type> <SCCS ID> yr/mo/da hr:mi:se <pgmr> DDDDD DDDDD 
@i DDDDD ... 

@x DDDDD ... 

@g DDDDD ... 

@m <MR number> 


@c <comments> 


@e 

The first line (@s) contains the number of lines inserted/deleted/unchanged respectively. The 
second line (@d) contains the type of the delta (currently, normal: D, and removed: R), the SCCS 
ID of the delta, the date and time of creation of the delta, the login name corresponding to the real 
user ID at the time the delta was created, and the serial numbers of the delta and its predecessor, 
respectively. 

The @i, @x, and @g lines contain the serial numbers of deltas included, excluded, and ignored, 
respectively. These lines are optional. 

The @m lines (optional) each contain one MR number associated with the delta; the @c lines con- 
tain comments associated with the delta. 

The @e line ends the delta table entry. 

User names 
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The list of login names and/or numerical group IDs of users who may add deltas to the file, 
separated by new-lines. The lines containing these login names and/or numerical group IDs are 
surrounded by the bracketing lines @u and @U. An empty fist allows anyone to make a delta. 

Flags 

Keywords used internally (see admin(l) for more information on their use). Each flag line takes 
the form: 

@f <flag> coptional text> 

The following flags are defined: 


@ft 

<type of program> 

@f V 

<program name> 

@f i 


@fb 


@f m 

•cmodule name> 

@ff 

<floor> 

@f c 

<ceiling> 

@fd 

<default-sid> 

@fn 


@fj 


@fl 

<lock-releases> 

@fq 

cuser defined> 


The t flag defines the replacement for the identification keyword. The v flag controls prompting 
for MR numbers in addition to comments; if the optional text is present it defines an MR number 
validity checking program. The i flag controls the waming/error aspect of the “No id keywords” 
message. When the i flag is not present, this message is only a warning; when the i flag is present, 
this message will cause a “fatal” error (the file will not be gotten, or the delta will not be made). 
When the b flag is present the -b keyletter may be used on the get command to cause a branch in 
the delta tree. The m flag defines the first choice for the replacement text of the sccsfile.5 
identification keyword. The f flag defines the “floor” release; the release below which no deltas 
may be added. The c flag defines the “ceiling” release; the release above which no deltas may be 
added. The d flag defines the default SID to be used when none is specified on a get command. 
The n flag causes delta to insert a “null” delta (a delta that applies no changes) in those releases 
that are skipped when a delta is made in a new release (for example, when delta 5.1 is made after 
delta 2.7, releases 3 and 4 are skipped). The absence of the n flag causes skipped releases to be 
completely empty. The j flag causes get to allow concurrent edits of the same base SID. The I 
flag defines a list of releases that are locked against editing (get( 1) with the -e keyletter). The q 
flag defines the replacement for the identification keyword. 

Comments 

Arbitrary text surrounded by the bracketing lines @t and @T. The comments section typically 
will contain a description of the file’s purpose. 

Body 

The body consists of text lines and control lines. Text lines don’t begin with the control character, 
control lines do. There are three kinds of control lines: insert, delete, and end, represented by: 

@1 DDDDD 
@D DDDDD 
@E DDDDD 

respectively. The digit string is the serial number corresponding to the delta for the control line. 
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SEE ALSO 

admin(l), delta(l), get(l), prs(l). 

Source Code Control System User’s Guide by L. E. Bonanni and C. A. Salemi. 


Sun Release 3.0 


Last change: 15 March 1983 


425 



SERVERS ( 5 ) 


FILE FORMATS 


SERVERS (5) 


NAME 

servers - inet server data base 
DESCRIPTION 

The servers file contains the list of servers that inetd( 8) operates. For each server a single line should be 
present with the following information: 

name of server 
protocol 
server location 

Items are separated by any number of blanks and/or tab characters. A “#” indicates the beginning of a 
comment; characters up to the end of the line are not interpreted by routines which search the file. 

The name of the server should be the official service name as contained in services (5). The protocol entry 
is either udp or top. The server location is the full path name of the server program. 

EXAMPLE 

The following example is taken from the Sun UNIX system. 


FILES 


top top /usr/eto/in.tcpd 

telnet top /usr/eto/in.telnetd 

shell top /etc/in.rshd 

login top /etc/in.rlogind 

exec top /usr/eto/in.rexecd 

top udp /usr/etc/in.ttopd 
syslog udp /usr/eto/in.syslog 

comsat udp /usr/eto/in.comsat 

talk udp /usr/etc/in.talkd 

time top /usr/ete/in.timed 

/etc/servers 


SEE ALSO 

services(5), inetd(8) 

BUGS 

Because of a limitation on the number of open files, this file must contain fewer than 27 lines. 
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NAME 

services - service name data base 

SYNOPSIS 

/etc/services 

DESCRIPTION 

The services file contains information regarding the known services available in the DARPA Internet For 
each service a single line should be present with the following information: 

official service name 
port number 
protocol name 
aliases 

Items are separated by any number of blanks and/or tab characters. The port number and protocol name 
are considered a single item ; a is used to separate the port and protocol (for instance, “512/tcp”). A 
“#” indicates the beginning of a comment; characters up to the end of the line are not interpreted by rou- 
tines which search the file. 

Service names may contain any printable character other than a field delimiter, newline, or comment char- 
acter. 

EXAMPLE 

Here is an example of the / etc/ services file from the Sun UNIX System. 

# 

# @(#)services 1.5 85/04/02 SMI 

# 

# Network services, Internet style 

# This file is never consulted when the yellow pages are running 

# 


echo 

7/udp 



discard 

9/udp 


sink null 

systat 

11/tcp 



daytime 

13/tcp 



netstat 

15/tcp 



ftp 

21/tcp 



telnet 

23/tcp 



smtp 

25/tcp 


mail 

time 

37/tcp 


timserver 

name 

42/tcp 


nameserver 

whois 

43/tcp 


nicname 

mtp 

57/tcp 


# deprecated 

hostnames 101/tcp 

sunrpc 

111/udp 

hostname 

# usually from sri-nic 

sunrpc 

# 

# Host specific functions 

# 

1 1 1/tcp 



tftp 

69/udp 



ije 

77/tcp 



finger 

79/tcp 



link 

87/tcp 


ttylink 

supdup 

ingreslock 1524/tcp 

95/tcp 




# 

# UNIX specific services 
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# 

exec 

512/tcp 



login 

513/tcp 



shell 

514/tcp 


cmd# no passwords used 

printer 

515/tcp 


spooler# experimental 

efs 

520/tcp 


# for LucasFilm 

courier 

530/tcp 


rpc# experimental 

biff 

512/udp 


comsat 

who 

513/udp 


whod 

syslog 

514/udp 



talk 

5 17/udp 



route 

520/udp 


router routed# 521 also 

new-rwho 550/udp 

new-who 

# experimental 

monitor 560/udp 

monitord 

# experimental 

monitor 

561/udp 


# experimental 

FILES 




/etc/services 





SEE ALSO 

getservent(3N) 

BUGS 

A name server should be used instead of a static file. A binary indexed file format should be available for 
fast access. 
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NAME 

tar - tape archive file format 
DESCRIPTION 

Tar, (the tape archive command) dumps several files into one, in a medium suitable for transportation. 

A “tar tape” or file is a series of blocks. Each block is of size TBLOCK. A file on the tape is represented 
by a header block which describes the file, followed by zero or more blocks which give the contents of the 
file. At the end of the tape are two blocks filled with binary zeros, as an end-of-file indicator. 

The blocks are grouped for physical I/O operations. Each group of n blocks (where n is set by the b 
keyletter on the tar( 1) command line — default is 20 blocks) is written with a single system call; on nine- 
track tapes, the result of this write is a single tape record. The last group is always written at the full size, 
so blocks after the two zero blocks contain random data. On reading, the specified or default group size is 
used for the first read, but if that read returns less than a full tape block, the reduced block size is used for 
further reads, unless the B keyletter is used. 

The header block looks like: 

#define TBLOCK 512 

#define NAMSIZ 100 

union hblock { 

char dummy [TBLOCK]; 
struct header { 

char name[NAMSIZ]; 

char mode[8]; 

char uid[8]; 

chargid[8]; 

char size[12]; 

char mtime[12]; 

char chksum[8]; 

char linkflag; 

char linkname[NAMSIZ]; 

} dbuf; 

}; 

Name is a null-terminated string. The other fields are zero-filled octal numbers in ASCII. Each field (of 
width w) contains w-2 digits, a space, and a null, except size and mtime, which do not contain the trailing 
null. Name is the name of the file, as specified on the tar command line. Files dumped because they were 
in a directory which was named in the command line have the directory name as prefix and /filename as 
suffix. Mode is the file mode, with the top bit masked off. Uid and gid are the user and group numbers 
which own the file. Size is the size of the file in bytes. Links and symbolic links are dumped with this field 
specified as zero. Mtime is the modification time of the file at the time it was dumped. Chksum is a 
decimal ASCII value which represents the sum of all the bytes in the header block. When calculating the 
checksum, the chksum field is treated as if it were all blanks. Linkflag is ASCII ‘0’ if the file is “normal” 
or a special file, ASCII ‘ 1’ if it is an hard link, and ASCII ‘2’ if it is a symbolic link. The name linked-to, if 
any, is in linkname, with a trailing null. Unused fields of the header are binary zeros (and are included in 
the checksum). 

The first time a given i-node number is dumped, it is dumped as a regular file. The second and subsequent 
times, it is dumped as a link instead. Upon retrieval, if a link entry is retrieved, but not the file it was linked 
to, an error message is printed and the tape must be manually re-scanned to retrieve the linked-to file. 

The encoding of the header is designed to be portable across machines. 

SEE ALSO 

tar(l) 
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BUGS 

Names or linknames longer than NAMSIZ produce error reports and cannot be dumped. 
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NAME 

term - terminal driving tables for nroff 
SYNOPSIS 

/usr/lib/term/tabname 

DESCRIPTION 

Nrojf(l) uses driving tables to customize its output for various types of output devices, such as terminals, 
line printers, daisy-wheel printers, or special output filter programs. These driving tables are written as C 
programs, compiled, and installed in the directory lusr/lib/term. The name of the output device is specified 
with the -T option of nroff. The structure of the terminal table is as follows: 

#define INCH 240 
struct { 

int bset; 
int breset; 
int Hor; 
int Vert; 
int Newline; 
int Char; 
int Em; 
int Halfline; 
int Adj; 
char *twinit; 
char *twrest; 
char *twnl; 
char *hlr; 
char *hlf; 
char *flr; 
char *bdon; 
char *bdoff; 
char *ploton; 
char *plotoff; 
char *up; 
char *down; 
char * right; 
char Heft; 

char *codetab[256-32]; 
char *zzz; 

} t; 

The meanings of the various fields are as follows: 

bset bits to set in the sgjiags field of the sgtty structure before output; see «y(4). 

breset bits to reset in the sgjiags field of the sgtty structure after output; see tty( 4). 

Hor horizontal resolution in fractions of an inch. 

Vert vertical resolution in fractions of an inch. 

Newline space moved by a newline (linefeed) character in fractions of an inch. 

Char quantum of character sizes, in fractions of an inch, (that is, a character is a multiple of Char 

units wide) 

Em size of an em in fractions of an inch. 

Halfline space moved by a half-linefeed (or half-reverse-linefeed) character in fractions of an inch. 


Sun Release 3.0 


Last change: 28 February 1985 


431 



TERM ( 5 ) 


FILE FORMATS 


TERM(5) 


Adj quantum of white space, in fractions of an inch, (that is, white spaces are a multiple of Adj 

units wide) 

Note: if this is less than the size of the space character (in units of Char; see below for how the 
sizes of characters are defined), nroff will output fractional spaces using plot mode. Also, if 
the -e switch to nroff is used, Adj is set equal to Hor by nroff. 

twinit set of characters used to initialize the terminal in a mode suitable for nroff. 

twrest set of characters used to restore the terminal to normal mode. 

twnl set of characters used to move down one line. 

hlr set of characters used to move up one-half line. 

hlf set of characters used to move down one-half line. 

fir set of characters used to move up one line. 

bdon set of characters used to turn on hardware boldface mode, if any. 

bdoff set of characters used to turn off hardware boldface mode, if any. 

ploton set of characters used to turn on hardware plot mode (for Diablo type mechanisms), if any. 

plotoff set of characters used to turn off hardware plot mode (for Diablo type mechanisms), if any. 

up set of characters used to move up one resolution unit (Vert) in plot mode, if any. 

down set of characters used to move down one resolution unit (Vert) in plot mode, if any. 

right set of characters used to move right one resolution unit (Hor) in plot mode, if any. 

left set of characters used to move left one resolution unit (Hor) in plot mode, if any. 

codetab definition of characters needed to print an nroff character on the terminal. The first byte is the 
number of character units (Char) needed to hold the character; that is, “\001” is one unit wide, 
“\002” is two units wide, etc. The high-order bit (0200) is on if the character is to be under- 
lined in underline mode (.ul). The rest of the bytes are the characters used to produce the char- 
acter in question. If the character has the sign (0200) bit on, it is a code to move the terminal 
in plot mode. It is encoded as: 

0100 bit on vertical motion. 

0100 bit off horizontal motion. 

040 bit on negative (up or left) motion. 

040 bit off positive (down or right) motion. 

037 bits number of such motions to make, 

zzz a zero terminator at the end. 

All quantities which are in units of fractions of an inch should be expressed as JNCU*numldenom, where 
num and denom are respectively the numerator and denominator of the fraction; that is, 1/48 of an inch 
would be written as “INCH/48”. 

If any sequence of characters does not pertain to the output device, that sequence should be given as a null 
string. 

The source code for the terminal name is in /usr/src/usr. bin/ nroff/ term/name. c If you add a new terminal 
type, modify the Makefile to reflect the change. By using the Makefile, everything will be compiled and 
installed automatically 

FILES 

/usr/lib/term/tabmzme driving tables 
tdtoname.c source for driving tables 
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SEE ALSO 

troff(l), term(7) 
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NAME 

termcap - terminal capability data base 

SYNOPSIS 

/etc/termcap 

DESCRIPTION 

Termcap is a data base describing terminals, used, for example, by vi'(l) and curses (SX). Terminals are 
described in termcap by giving a set of capabilities which they have, and by describing how operations are 
performed. Padding requirements and initialization sequences are included in termcap. 

Each entry in the termcap file describes a terminal, and is a line consisting of a number of fields separated 
by characters. The first entry for each terminal gives the names which are known for the terminal, 
separated by T characters. The first name is always 2 characters long and is used by older version 6 sys- 
tems which store the terminal type in a 16 bit word in a systemwide data base. The second name given is 
the most common abbreviation for the terminal, and the last name given should be a long name fully identi- 
fying the terminal. The second name should contain no blanks; the last name may well contain blanks for 
readability. Entries may continue onto multiple lines by giving a \ as the last character of a line, and empty 
fields may be included for readability. 

Capabilities in termcap are all introduced by two-character codes, and are of three types: 

Boolean capabilities indicate that the terminal has some particular feature. Boolean capabilities are 
simply written between the characters, and are indicated by the word ‘bool’ in the type 
column of the capabilities table below. 

Numeric capabilities supply information such as the size of the terminal or the size of particular delays. 

Numeric capabilities are indicated by the word ‘num’ in the type column of the capabilities 
table below. Numeric capabilities are given by the two-character capability code followed by 
the ‘#’ character and then the numeric value. For example: :co#80: is a numeric entry stat- 
ing that this terminal has 80 columns. 

String capabilities give a sequence which can be used to perform particular terminal operations such 
as cursor motion. String valued capabilities are indicated by the word ‘str’ in the type column 
of the capabilities table below. String valued capabilities are given by the two-character capa- 
bility code followed by an *=’ sign and then a string ending at the next following For 
example, :ce=16\E*S: is a sample entry for clear to end-of-line. 

CAPABILITIES 


(P) 

indicates padding may be specified 

(P*) 

indicates that padding may be based on the number of lines affected 

Name Type Pad? 

Description 

ae 

str 

(P) 

End alternate character set 

al 

str 

(P*) 

Add new blank line 

am 

bool 


Terminal has automatic margins 

as 

str 

(P) 

Start alternate character set 

be 

str 


Backspace if not 'H 

bl 

str 


Audible bell character 

bs 

bool 


Terminal can backspace with A H 

bt 

str 

(P) 

Back tab 

bw 

bool 


Backspace wraps from column 0 to last column 

CC 

str 


Command character in prototype if terminal settable 

cd 

str 

(P*) 

Clear to end of display 

ce 

str 

(P) 

Clear to end of line 

ch 

str 

(P) 

Like cm but horizontal motion only, line stays same 

cl 

str 

(P*) 

Clear screen 

cm 

str 

(P) 

Cursor motion 

CO 

num 


Number of columns in a line 

cr 

str 

(P*) 

Carriage return, (default *M) 
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cs 

str 

(P) 

Change scrolling region (vtlOO), like cm 

ct 

str 


Clear all tab stops 

cv 

str 

(P) 

Like ch but vertical only. 

da 

bool 


Display may be retained above 

dB 

num 


Number of millisec of bs delay needed 

db 

bool 


Display may be retained below 

dC 

num 


Number of millisec of cr delay needed 

dc 

str 

(P*) 

Delete character 

dF 

num 


Number of millisec of ff delay needed 

dl 

str 

(P*) 

Delete line 

dm 

str 


Delete mode (enter) 

dN 

num 


Number of millisec of nl delay needed 

do 

str 


Down one line 

dT 

num 


Number of millisec of tab delay needed 

ed 

str 


End delete mode 

ei 

str 


End insert mode; give “:ei=:” if ic 

eo 

str 


Can erase overstrikes with a blank 

ff 

str 

(P*) 

Hardcopy terminal page eject (default A L) 

he 

bool 


Hardcopy terminal 

hd 

str 


Half-line down (forward 1/2 linefeed) 

ho 

su- 


Home cursor (if no cm) 

hu 

ss- 


Half-line up (reverse 1/2 linefeed) 

hz 

str 


Hazeltine; can’t print "’s 

ic 

str 

(P) 

Insert character 

if 

str 


Name of file containing is 

im 

bool 


Insert mode (enter); give “:im=:” if ic 

in 

bool 


Insert mode distinguishes nulls on display 

ip 

str 

(P*) 

Insert pad after character inserted 

is 

str 


Terminal initialization string 

k0-k9 str 


Sent by “other” function keys 0-9 

kb 

str 


Sent by backspace key 

kd 

str 


Sent by terminal down arrow key 

ke 

str 


Out of “keypad transmit” mode 

kh 

str 


Sent by home key - 

kl 

str 


Sent by terminal left arrow key 

kn 

num 


Number of “other” keys 

ko 

str 


Termcap entries for other non-function keys 

kr 

str 


Sent by terminal right arrow key 

ks 

str 


Put terminal in “keypad transmit” mode 

ku 

str 


Sent by terminal up arrow key 

10-19 

str 


Labels on “other” function keys 

le 

str 


Move cursor left one place 

li 

num 


Number of lines on screen or page 

11 

str 


Last line, first column (if no cm) 

ma 

str 


Arrow key map, used by vi version 2 only 

mb 

str 


Turn on blinking 

md 

str 


Enter bold (extra-bright) mode 

me 

str 


Turn off all attributes, normal mode 

mh 

str 


Enter dim (half-bright) mode 

mi 

bool 


Safe to move while in insert mode 

ml 

str 


Memory lock on above cursor. 

mr 

str 


Enter reverse mode 

ms 

bool 


Safe to move while in standout and underline mode 
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mu 

str 


Memory unlock (turn off memory lock). 

nc 

bool 


No correctly working carriage return (DM2500, H2000) 

nd 

str 


Non-destructive space (cursor right) 

nl 

str 

(P*) 

Newline character (default \n) 

ns 

bool 


Terminal is a CRT but doesn’t scroll. 

os 

bool 


Terminal overstrikes 

pc 

str 


Pad character (rather than null) 

pt 

bool 


Has hardware tabs (may need to be set with is) 

rf 

str 


Reset file, like if but for reset (1) 

rs 

str 


Reset string, like is but for reset ( 1) 

se 

str 


End stand out mode 

sf 

str 

(P) 

Scroll forwards 

Sg 

num 


Number of blank chars left by so or se 

so 

str 


Begin stand out mode 

sr 

str 

(P) 

Scroll reverse (backwards) 

St 

str 


Set a tab in all rows, current column 

ta 

str 

(P) 

Tab (other than A I or with padding) 

tc 

sa- 


Entry of similar terminal - must be last 

te 

sh - 


String to end programs that use cm 

ti 

str 


String to begin programs that use cm 

uc 

sa- 


Underscore one char and move past it 

ue 

sh - 


End underscore mode 

ug 

num 


Number of blank chars left by us or ue 

ul 

bool 


Terminal underlines even though it doesn’t overstrike 

up 

str 


Upline (cursor up) 

us 

str 


Start underscore mode 

vb 

str 


Visible bell (may not move cursor) 

ve 

str 


Sequence to end open/visual mode 

vs 

str 


Sequence to start open/visual mode 

vt 

num 


Virtual terminal number (CB/UNIX) 

xb 

bool 


Beehive (fl=escape, f2=ctrl C) 

xn 

bool 


A newline is ignored after a wrap (Concept) 

xr 

bool 


Return acts like ce \r \n (Delta Data) 

xs 

bool 


Standout not erased by writing over it (HP 264?) 

xt 

bool 


Tabs are destructive, magic so char (Teleray 1061) 

A Sample Entry 



The following example describes the wyse terminal entry. 

wv|wyse-vp|wyse|Wyse 50 in ADDS Viewpoint emulation mode with "enhance" on: 
:am:cr= , 'M:do=''J:nl= , 'J:bl=''G:if=/usr/lib/tabset/wyse-adds: :le= A H:bs:li#24:co#80:cm=EY%+ %+ 

:cd=Ek:ce=EK:nd=T: :up= A Z:cl= A L:fi= A A:kl= A U:kr=T:kd= A J:ku= A Z:kh= A A: 

:pt: so=“N : se=''0:us= , 'N:ue= /> 0: :dl=El:al=EM:im=Eq:ei=Er:dc=EW: 

:is=E‘ 72E‘9 A OEr:rs=E‘ 72E‘9 A OEr: 

Types of Capabilities 

Capabilities in termcap are of three types: Boolean capabilities which indicate that the terminal has some 
particular feature, numeric capabilities giving the size of the terminal or the size of particular delays, and 
string capabilities, which give a sequence which can be used to perform particular terminal operations. All 
capabilities have two letter codes. 

Boolean capabilities are introduced simply by stating the two-character capability code in the field 
between characters. For instance, the fact that the Concept has “automatic margins” (that 
is, an automatic return and linefeed when the end of a line is reached) is indicated by the capa- 
bility am. Hence the description of the Concept includes am. 
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capabilities are followed by the character “#’ and then the value. Thus co which indicates the 
number of columns the terminal has gives the value ‘80’ for the Concept 

valued capabilities, such as ce (clear to end of line sequence) are given by the two character 
code, an *=’, and then a string ending at the next following A delay in milliseconds may 
appear after the *=’ in such a capability, and padding characters are supplied by the editor after 
the remainder of the string is sent to provide this delay. The delay can be either a integer, for 
instance, ‘20’, or an integer followed by an that is, ‘3*’. A ‘*’ indicates that the padding 
required is proportional to the number of lines affected by the operation, and the amount given 
is the per-affected-unit padding required. When a is specified, it is sometimes useful to 
give a delay of the form ‘3.5’ to specify a delay per unit to tenths of milliseconds. 

A number of escape sequences are provided in the string valued capabilities for easy encoding 
of characters there. A \E maps to an escape character, A x maps to a control-x for any 
appropriate x, and the sequences \n \r \t \b \f give a newline, return, tab, backspace and 
formfeed. Finally, characters may be given as three octal digits after a \, and the characters A 
and \ may be given as \* and \\. If it is necessary to place a : in a capability it must be escaped 
in octal as \072. If it is necessary to place a null character in a string capability it must be 
encoded as \200. The routines which deal with termcap use C strings, and strip the high bits of 
the output very late so that a \200 comes out as a \000 would. 

Preparing Descriptions 

We now outline how to prepare descriptions of terminals. The most effective way to prepare a terminal 
description is by imitating the description of a similar terminal in termcap and to build up a description gra- 
dually, using partial descriptions with ex to check that they are correct. Be aware that a very unusual termi- 
nal may expose deficiencies in the ability of the termcap file to describe it or bugs in ex. To easily test a 
new terminal description you can set the environment variable TERMCAP to a pathname of a file contain- 
ing the description you are working on and the editor will look there rather than in letcltermcap. 
TERMCAP can also be set to the termcap entry itself to avoid reading the file when starting up the editor. 

Basic capabilities 

The number of columns on each line for the terminal is given by the co numeric capability. If the terminal 
is a CRT, then the number of lines on the screen is given by the li capability. If the terminal wraps around 
to the beginning of the next line when it reaches the right margin, then it should have the am capability. If 
the terminal can clear its screen, then this is given by the cl string capability. If the terminal can backspace, 
then it should have the bs capability, unless a backspace is accomplished by a character other than 'H (ugh) 
in which case you should give this character as the be string capability. If it overstrikes (rather than clear- 
ing a position when a character is struck over) then it should have the os capability. 

A very important point here is that the local cursor motions encoded in termcap are undefined at the left 
and top edges of a CRT terminal. The editor will never attempt to backspace around the left edge, nor will it 
attempt to go up locally off the top. The editor assumes that feeding off the bottom of the screen will cause 
the screen to scroll up, and the am capability tells whether the cursor sticks at the right edge of the screen. 
If the terminal has switch selectable automatic margins, the termcap file usually assumes that this is on, that 
is, am. 

These capabilities suffice to describe hardcopy and “glass-tty” terminals. Thus the model 33 teletype is 
described as 

t3 1 33 1 tty33:co#72:os 

while the Lear Siegler adm-3 is described as 

cl | adm3|3|lsi adm3:am:bs:cl=“Z:li#24:co#80 
Cursor addressing 


Numeric 

String 
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Cursor addressing in the terminal is described by a cm string capability, with printf(3S) like escapes %x in 
it These substitute to encodings of the current line or column position, while other characters are passed 
through unchanged. If the cm string is thought of as being a function, then its arguments are the line and 
then the column to which motion is desired, and the % encodings have the following meanings: 

%d as in printf, 0 origin 

%2 like %2d 

%3 like %3d 

%. like %c 

%+x adds x to value, then %. 

%>xy if value > x adds y, no output 
%r reverses order of line and column, no output 
%i increments line/column (for 1 origin) 

%% gives a single % 

%n exclusive or row and column with 0140 PM2500) 

%B BCD (16*(x/10)) + (x%10), no output. 

%D Reverse coding (x-2*(x%16)), no output. (Delta Data). 

Consider the HP2645, which, to get to row 3 and column 12, needs to be sent \E&al2c03Y padded for 6 
milliseconds. Note that the order of the rows and columns is inverted here, and that the row and column 
are printed as two digits. Thus its cm capability is “cm=6\E&%r%2c%2Y”. The Microterm act-iv needs 
the current row and column sent preceded by a A T, with the row and column simply encoded in binary, 
“cm= A T%.%.”. Terminals which use need to be able to backspace the cursor (bs or be), and to 
move the cursor up one line on the screen (up introduced below). This is necessary because it is not 
always safe to transmit \t, \n A D and \r, as the system may change or discard them. 

A final example is the LSI ADM-3a, which uses row and column offset by a blank character, thus 
“cm=\E=%+ %+ 

Cursor motions 

If the terminal can move the cursor one position to the right, leaving the character at the current position 
unchanged, then this sequence should be given as nd (non-destructive space). If it can move the cursor up 
a line on the screen in the same column, this should be given as up. If the terminal has no cursor address- 
ing capability, but can home the cursor (to very upper left comer of screen) then this can be given as ho; 
similarly a fast way of getting to the lower left hand comer can be given as 11 ; this may involve going up 
with up from the home position, but the editor will never do this itself (unless II does) because it makes no 
assumption about the effect of moving up from the home position. 

Area clears 

If the terminal can clear from the current position to the end of the line, leaving the cursor where it is, this 
should be given as ce. If the terminal can clear from the current position to the end of the display, then this 
should be given as cd. The editor only uses cd from the first column of a line. 

Insert/delete line 

If the terminal can open a new blank line before the line where the cursor is, this should be given as al; this 
is done only from the first position of a line. The cursor must then appear on the newly blank line. If the 
terminal can delete the line which the cursor is on, then this should be given as dl; this is done only from 
the first position on the line to be deleted. If the terminal can scroll the screen backwards, then this can be 
given as sb, but just al suffices. If the terminal can retain display memory above then the da capability 
should be given; if display memory can be retained below then db should be given. These let the editor 
understand that deleting a line on the screen may bring non-blank lines up from below or that scrolling 
back with sb may bring down non-blank lines. 

Insert/delete character 
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There are two basic kinds of intelligent terminals with respect to insert/delete character which can be 
described using termcap. The most common insert/delete character operations affect only the characters on 
the current line and shift characters off the end of the line rigidly. Other terminals, such as the Concept 
100 and the Perkin Elmer Owl, make a distinction between typed and untyped blanks on the screen, shift- 
ing upon an insert or delete only to an untyped blank on the screen which is either eliminated, or expanded 
to two untyped blanks. You can find out which kind of terminal you have by clearing the screen and then 
typing text separated by cursor motions. Type “abc def ’ using local cursor motions (not spaces) 
between the “abc” and the “def’. Then position the cursor before the “abc” and put the terminal in 
insert mode. If typing characters causes the rest of the line to shift rigidly and characters to fall off the end, 
then your terminal does not distinguish between blanks and untyped positions. If the “abc” shifts over to 
the “def’ which then move together around the end of the current line and onto the next as you insert, you 
have the second type of terminal, and should give the capability in, which stands for “insert null”. If your 
terminal does something different and unusual then you may have to modify the editor to get it to use the 
insert mode your terminal defines. We have seen no terminals which have an insert mode not not fallin g 
into one of these two classes. 

The editor can handle both terminals which have an insert mode, and terminals which send a simple 
sequence to open a blank position on the current line. Give as im the sequence to get into insert mode, or 
give it an empty value if your terminal uses a sequence to insert a blank position. Give as ei the sequence 
to leave insert mode (give this, with an empty value also if you gave im so). Now give as ic any sequence 
needed to be sent just before sending the character to be inserted. Most terminals with a true insert mode 
will not give ic, terminals which send a sequence to open a screen position should give it here. (Insert 
mode is preferable to the sequence to open a position on the screen if your terminal has both.) If post insert 
padding is needed, give this as a number of milliseconds in ip (a string option). Any other sequence which 
may need to be sent after an insert of a single character may also be given in ip. 

It is occasionally necessary to move around while in insert mode to delete characters on the same line (for 
example, if there is a tab after the insertion position). If your terminal allows motion while in insert mode 
you can give the capability mi to speed up inserting in this case. Omitting mi will affect only speed. 
Some terminals (notably Datamedia’s) must not have mi because of the way their insert mode works. 

Finally, you can specify delete mode by giving dm and ed to enter and exit delete mode, and dc to delete a 
single character while in delete mode. 

Highlighting, underlining, and visible bells 

If your terminal has sequences to enter and exit standout mode these can be given as so and se respectively. 
If there are several flavors of standout mode (such as inverse video, blinking, or underlining - half bright is 
not usually an acceptable “standout” mode unless the terminal is in inverse video mode constantly) the 
preferred mode is inverse video by itself. If the code to change into or out of standout mode leaves one or 
even two blank spaces on the screen, as the TVI 912 and Teleray 1061 do, then sg should be given to tell 
how many spaces are left. 

Codes to begin underlining and end underlining can be given as us and ue respectively. If they leave blank 
spaces on the screen, set ug. If the terminal has a code to underline the current character and move the cur- 
sor one space to the right, such as the Microterm Mime, this can be given as uc. (If the underline code 
does not move the cursor to the right, give the code followed by a nondestructive space.) 

Many terminals, such as the HP 2621, automatically leave standout mode when they move to a new line or 
the cursor is addressed. Programs using standout mode should exit standout mode before moving the cur- 
sor or sending a newline. 

If the terminal has a way of flashing the screen to indicate an error quietly (a bell replacement) then this 
can be given as vb; it must not move the cursor. If the terminal should be placed in a different mode dur- 
ing open and visual modes of ex, this can be given as vs and ve, sent at the start and end of these modes 
respectively. These can be used to change, for example, from a underline to a block cursor and back. 
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If the terminal needs to be in a special mode when running a program that addresses the cursor, the codes 
to enter and exit this mode can be given as ti and te. This arises, for example, from terminals like the Con- 
cept with more than one page of memory. If the terminal has only memory relative cursor addressing and 
not screen relative cursor addressing, a one screen-sized window must be fixed into the terminal for cursor 
addressing to work properly. 

If your terminal correctly generates underlined characters (with no special codes needed) even though it 
does not overstrike, then you should give the capability ul. If overstrikes are erasable with a blank, then 
this should be indicated by giving eo. 

ANSI terminals have modes for the character highlighting. Dim characters may be generated in dim mode, 
entered by mh; reverse video characters in reverse mode, entered by mr; bold characters in bold mode, 
entered by md; and normal mode characters restored by turning off all attributes with me. 

Keypad 

If the terminal has a keypad that transmits codes when the keys are pressed, this information can be given. 
Note that it is not possible to handle terminals where the keypad only works in local (this applies, for 
example, to the unshifted HP 2621 keys). If the keypad can be set to transmit or not transmit, give these 
codes as ks and ke. Otherwise the keypad is assumed to always transmit. The codes sent by the left arrow, 
right arrow, up arrow, down arrow, and home keys can be given as kl, kr, ku, kd, and kh respectively. If 

there are function keys such as fO, fl f9, the codes they send can be given as kO, kl, k9. If these 

keys have labels other than the default fO through f9, the labels can be given as 10, II 19. If there are 

other keys that transmit the same code as the terminal expects for the corresponding function, such as clear 
screen, the termcap 2 letter codes can be given in the ko capability, for example, “:ko=cl,U,sf,sb:”, which 
says that the terminal has clear, home down, scroll down, and scroll up keys that transmit the same thing as 
the cl, 11, sf, and sb entries. 

The ma entry is also used to indicate arrow keys on terminals which have single character arrow keys. It is 
obsolete but still in use in version 2 of vi, which must be run on some minicomputers due to memory limi- 
tations. This field is redundant with kl, kr, ku, kd, and kh. It consists of groups of two characters. In each 
group, the first character is what an arrow key sends, the second character is the corresponding vi com- 
mand. These commands are h for kl, j for kd, k for ku, 1 for kr, and H for kh. For example, the mime 
would be :ma= A Kj A Zk A Xl: indicating arrow keys left ( A H), down ( A K), up ( A Z), and right ( A X). (There is no 
home key on the mime.) 

Miscellaneous 

If the terminal requires other than a null (zero) character as a pad, then this can be given as pc. 

If tabs on the terminal require padding, or if the terminal uses a character other than A I to tab, then this can 
be given as ta. 

Hazeltine terminals, which don’t allow characters to be printed should indicate hz. Datamedia termi- 
nals, which echo carriage-return linefeed for carriage return and then ignore a following linefeed should 
indicate nc. Early Concept terminals, which ignore a linefeed immediately after an am wrap, should indi- 
cate xn. If an erase-eol is required to get rid of standout (instead of merely writing on top of it), xs should 
be given. Teleray terminals, where tabs turn all characters moved over to blanks, should indicate xt. Other 
specific terminal problems may be corrected by adding more capabilities of the form xx. 

Other capabilities include is, an initialization string for the terminal, and if, the name of a file containing 
long initialization strings. These strings are expected to properly clear and then set the tabs on the terminal, 
if the terminal has settable tabs. If both are given, is will be printed before if. This is useful where if is 
lusrllib/tabset/std but is clears the tabs first. 

Similar Terminals 

If there are two very similar terminals, one can be defined as being just like the other with certain excep- 
tions. The string capability tc can be given with the name of the similar terminal. This capability must be 
last and the combined length of the two entries must not exceed 1024. Since termlib routines search the 
entry from left to right, and since the tc capability is replaced by the corresponding entry, the capabilities 
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given at the left override the ones in the similar terminal. A capability can be canceled with xx@ where xx 
is the capability. For example, the entry 

hn 1 2621nl:ks@:ke@:tc=2621: 

defines a 262 lnl that does not have the ks or ke capabilities, and hence does not turn on the function key 
labels when in visual mode. This is useful for different modes for a terminal, or for different user prefer- 
ences. 

FILES 

/etc/termcap file containing terminal descriptions 
SEE ALSO 

ex(l), curses(3X), termcap(3X), tset(l), vi(l), ul(l), more(l) 

BUGS 

Ex allows only 256 characters for string capabilities, and the routines in termcap{ 3X) do not check for 
overflow of this buffer. The total length of a single entry (excluding only escaped newlines) may not 
exceed 1024. 

The ma, vs, and ve entries are specific to the vt program. 

Not all programs support all entries. There are entries that are not supported by any program. 
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NAME 

tp - DEC/mag tape formats 
DESCRIPTION 

Tp dumps files to and extracts files from DECtape and magtape. The formats of these tapes are the same 
except that magtapes have larger directories. 

Block zero contains a copy of a stand-alone bootstrap program. See reboot ( 8). 

Blocks 1 through 24 for DECtape (1 through 62 for magtape) contain a directory of the tape. There are 192 
(resp. 496) entries in the directory; 8 entries per block; 64 bytes per entry. Each entry has the following 
format: 

struct { 


char 

pathname[32]; 

unsigned short 

mode; 

char 

uid; 

char 

gid; 

char 

unusedl; 

char 

size[3]; 

long 

modtime; 

unsigned short 

tapeaddr; 

char 

unused2[16]; 

unsigned short 

checksum; 


}; 

The path name entry is the path name of the file when put on the tape. If the pathname starts with a zero 
word, the entry is empty. It is at most 32 bytes long and ends in a null byte. Mode, uid, gid, size and time 
modified are the same as described under i-nodes (see file system fs( 5)). The tape address is the tape block 
number of the start of the contents of the file. Every file starts on a block boundary. The file occupies 
(size+5 1 1)/5 12 blocks of continuous tape. The checksum entry has a value such that the sum of the 32 
words of the directory entry is zero. 

Blocks above 25 (resp. 63) are available for file storage. 

A fake entry has a size of zero. 

SEE ALSO 

fs(5) 

BUGS 

The pathname, uid, gid, and size fields are too small. 
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NAME 

ttys - terminal initialization data 
DESCRIPTION 

The ttys file is read by the init program and specifies which terminal special files are to have a process 
created for them so that people can log in. There is one line in the ttys file per special file associated with a 
terminal. 

The first character of a line in the ttys file is either ‘O’ or T. If the first character on the line is a ‘O’, the 
init program ignores that line. If the first character on the line is a T, the init program creates a login pro- 
cess for that line. 

The second character on each line is used as an argument to getty( 8), which performs such tasks as baud- 
rate recognition, reading the login name, and calling login. For normal lines, the second character is ‘O’; 
other characters can be used, for example, with hard-wired terminals where speed recognition is unneces- 
sary or which have special characteristics. The remainder of the line is the terminal’s entry in the device 
directory, /dev. 

Getty uses the second character in the ttys file to look up the characteristics of the terminal in the 
/etc/gettytab file. Consult the gettytab(5) manual page for an explanation of the layout of letclgettytab. 

FILES 

/etc/ttys 
SEE ALSO 

init(8), getty(8), login(l), gettytab(5) 
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NAME 

ttytype - data base of terminal types by port 

SYNOPSIS 

/etc/ttytype 

DESCRIPTION 

Ttytype is a database containing, for each tty port on the system, the kind of terminal that is attached to it. 
There is one line per port, containing the terminal kind (as a name listed in termcap (5)), a space, and the 
name of the tty, minus /dev/. 

This information is read by tset(\) and by login( 1) to initialize the TERM variable at login time. 

SEE ALSO 

tset(l), login(l) 

BUGS 

Some lines are merely known as “dialup” or “plugboard”. 
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NAME 

types - primitive system data types 
SYNOPSIS 

#include <sys/types.h> 

DESCRIPTION 

The data types defined in the include file are used in UNIX system code; some data of these types are 
accessible to user code: 

/* @(#)types.h 2.4 85/02/06 SMI; from UCB 4.11 83/07/01*/ 


/* 

* Basic system types and major/minor device constructing/busting macros. 
*/ 

#ifhdef _TYPES_ 

#define _TYPES_ 

/* major part of a device */ 

#define major(x) ((int)(((unsigned)(x)»8)&0377)) 

/* minor part of a device */ 

#define minor(x) ((int)((x)&0377)) 


/* make a device number */ 

#define makedev(x,y) ((dev_t)(((x)«8) | (y))) 


typedef unsigned char 
typedef unsigned short 
typedef unsigned int 
typedef unsigned long 
typedef unsigned short 


uchar; 

ushort; 

uint; 

ulong; 

ushort;/* System V compatibility */ 


#ifdef vax 
typedef struct 
typedef struct 
int 

} labelt; 

#endif 

#ifdef mc68000 
typedef struct 
typedef struct 
int 

} label t; 

#endif 

typedef struct 
typedef long 
typedef char * 
typedef u_long 
typedef long 
typedef int 
typedef int 
typedef short 
typedef int 


_physadr { int r[l]; } *physadr; 

label_t{ 

val[14]; 


_physadr { short r[l]; } *physadr; 

label_t{ 

val[13]; 


_quad { long val[2]; } quad; 

daddr_t; 

caddrt; 

inot; 

swblk_t; 

size_t; 

timet; 

dev_t; 

off_t; 
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typedef struct fd_set { int fdsM>its[l]; } fd set; 

#endif 

The form daddr t is used for disk addresses, see fs( 5). Times are encoded in seconds since 00:00:00 GMT, 
January 1, 1970. The major and minor parts of a device code specify kind and unit number of a device and 
are installation-dependent. Offsets are measured in bytes from the beginning of a file. The label t vari- 
ables are used to save the processor state while another process is running. 

SEE ALSO 

fs(5), time(3C), lseek(2), adb(lS) 
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NAME 

utmp, wtmp, lastlog — login records 

SYNOPSIS 

#include <utmp.h> 

DESCRIPTION 

The utmp file records information about who is currently using the system. The file is a sequence of entries 
with the following structure declared in the include file: 

/* @(#)utmp.h 1.3 85/07/01 SMI; from UCB 4.2 83/05/22 */ 

/* 

* Structure of utmp and wtmp files. 

* 


* Assuming the number 8 is unwise. 
*/ 


struct utmp { 



char 

ut_line[8]; 

/* tty name */ 

char 

ut_name[8]; 

/* user id */ 

char 

ut_host[16]; 

/* host name, if remote */ 

long 

uttime; 

/* time on */ 


}; 


/* 

* This is a utmp entry that does not correspond to a genuine user 
*1 

#define nonuser(ut) ((ut).ut_host[0] == 0 && stmcmp((ut).ut_line, "tty", 3) == 0 && ((ut).ut_line[3] 

This structure gives the name of the special file associated with the user’s terminal, the user’s login name, 
and the time of the login in the form of time (1C). 

The wtmp file records all logins and logouts. A null user name indicates a logout on the associated termi- 
nal. Furthermore, the terminal name “’ indicates that the system was rebooted at the indicated time; the 
adjacent pair of entries with terminal names T and *}’ indicate the system-maintained time just before and 
just after a date command has changed the system’s idea of the time. 

wtmp is maintained by login( 1) and init( 8). Neither of these programs creates the file, so if it is removed, 
record-keeping is turned off. It is summarized by ac(8). 

lusrladmlwtmp is appened to whenever a user logs in or out, and should be truncated periodically. 

The lastlog file records the most recent login-date for every user logged in. When reporting (and updating) 
the most recent login date, login( 1) performs an to a byte-offset in lusrladmllastlog corresponding to the 
userid. Because the count of userids may be high, whereas the number actual users may be small within a 
network environment, the bulk of this file may never be allocated by the file system even though an offset 
may appear to be quite large. Although Is may show it to be large, chances are that this file need not trun- 
cated. du( 1) will report the correct (smaller) amount of space actually allocated to it 

FILES 

/etc/utmp 

/usr/adm/wtmp 

SEE ALSO 

login(l), init(8), who(l), ac(8) 
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NAME 

uuencode - format of an encoded uuencode file 
DESCRIPTION 

Files output by uuencode(lC) consist of a header line, followed by a number of body lines, and a trailer 
line. Uudecode will ignore any lines preceding the header or following the trailer. Lines preceding a 
header must not, of course, look like a header. 

The header line is distinguished by having the first 6 characters “begin ”. The word begin is followed by a 
mode (in octal), and a string which names the remote file. Spaces separate the three items in the header 
line. 

The body consists of a number of lines, each at most 62 characters long (including the trailing newline). 
These consist of a character count, followed by encoded characters, followed by a newline. The character 
count is a single printing character, and represents an integer, the number of bytes the rest of the line 
represents. Such integers are always in the range from 0 to 63 and can be determined by subtracting the 
character space (octal 40) from the character. 

Groups of 3 bytes are stored in 4 characters, 6 bits per character. All are offset by a space to make the 
characters printing. The last line may be shorter than the normal 45 bytes. If the size is not a multiple of 3, 
this fact can be determined by the value of the count on the last line. Extra garbage will be included to 
make the character count a multiple of 4. The body is terminated by a line with a count of zero. This line 
consists of one ASCII space. 

The trailer line consists of “end” on a line by itself. 

SEE ALSO 

uuencode(lC), uudecode(lC), uusend(lC), uucp(lC), mail(l) 
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NAME 

vfont - font formats 

SYNOPSIS 

#include <vfont.h> 


DESCRIPTION 

The fonts used by the window system and printer/plotters have the following format. Each font is in a file, 
which contains a header, an array of character description structures, and an array of bytes containing the 
bit maps for the characters. The header has the following format: 


struct header { 

short magic; 

unsigned short size; 
short maxx; 

short maxy; 

short xtend; 

}; 

#define VFONT MAGIC 


/* Magic number VFONT MAGIC */ 
I* Total # bytes of bitmaps */ 

I* Maximum horizontal glyph size *1 
I* Maximum vertical glyph size */ 

/* (unused) */ 

0436 


Maxx and maxy are intended to be the maximum horizontal and vertical size of any glyph in the font, in 
raster lines. (A glyph is just a printed representation of a character, in a particular size and font.) The size 
is the total size of the bit maps for the characters in bytes. The xtend field is not currently used. 

After the header is an array of NUMDISPATCH structures, one for each of the possible characters in the 
font Each element of the array has the form: 


FILES 


struct dispatch { 

unsigned short addr; /* &(glyph) - &(start of bitmaps) */ 

short nbytes; /* # bytes of glyphs (0 if no glyph) */ 

char up, down, left, right; I* Widths from baseline point *1 

short width; /* Logical width, used by troff */ 

}; 

#define NUMDISPATCH 256 

The nbytes field is nonzero for characters which actually exist. For such characters, the addr field is an 
offset into the bit maps to where the character’s bit map begins. The up, down, left, and right fields are 
offsets from the base point of the glyph to the edges of the rectangle which the bit map represents. (The 
imaginary “base point” is a point which is vertically on the “base line” of the glyph (the bottom line of a 
glyph which doesn’t have a descender) and horizontally near the left edge of the glyph; often 3 or so pixels 
past the left edge.) The bit map contains up+down rows of data for the character, each of which has 
left+right columns (bits). Each row is rounded up to a number of bytes. The width field represents the log- 
ical width of the glyph in bits, and shows the horizontal displacement to the base point of the next glyph. 

/usr/lib/vfont/* 

/usr/lib/fonts/fixedwidthfonts/* 


SEE ALSO 

troff(l), pti(l), vfontinfo(l), vswap(l) 

BUGS 

A machine-independent font format should be defined. The shorts in the above structures contain different 
bit patterns depending whether the font file is for use on a Vax or a Sun. The vswap program must be used 
to convert one to the other. 
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NAME 

vgrindefs - vgrind’s language definition data base 

SYNOPSIS 

/usr/Iib/vgrindefs 

DESCRIPTION 

Vgrindefs contains all language definitions for vgrind. The data base is very similar to termcap(5). 

FIELDS 

The following table names and describes each field. 

Name Type Description 

pb str regular expression for start of a procedure 

bb str regular expression for start of a lexical block 

be str regular expression for the end of a lexical block 

cb str regular expression for the start of a comment 

ce str regular expression for the end of a comment 

sb str regular expression for the start of a string 

se str regular expression for the end of a string 

lb str regular expression for the start of a character constant 

le str regular expression for the end of a character constant 

tl bool present means procedures are only defined at the top 
lexical level 

oc bool present means upper and lower case are equivalent 

kw str a list of keywords separated by spaces 

Example 

The following entry, which describes the C language, is typical of a language entry. 

C|c: :pb='\d?*M?\p\d??):bb={:be=}:cb=/*:ce=*/:sb=":se=\e":\ 

:lb=’:le=\e’:tl:\ 

:kw=asm auto break case char continue default do double else enum\ 
extern float for fortran goto if int long register return short\ 
sizeof static struct switch typedef union unsigned while #define\ 

#else #endif #if #ifdef #ifndef #include #undef # define else endif\ 
if ifdef ifndef include undef: 

Note that the first field is just the language name (and any variants of it). Thus the C language could be 
specified to vgrind( 1) as "c" or "C". 

Entries may continue onto multiple lines by giving a \ as the last character of a line. Capabilities in vgrin- 
defs are of two types: Boolean capabilities which indicate that the language has some particular feature and 
string capabilities which give a regular expression or keyword list. 

REGULAR EXPRESSIONS 

Vgrindefs uses regular expression which are very similar to those of ex(V) and lex( 1). The characters ‘ A ’, 
'$’, and ‘V are reserved characters and must be "quoted" with a preceding \ if they are to be included as 
normal characters. The metasymbols and their meanings are: 

$ the end of a line 

the beginning of a line 

\d a delimiter (space, tab, newline, start of line) 

\a matches any string of symbols (like .* in lex) 

\p matches any alphanumeric name. In a procedure definition (pb) the string that matches this sym- 
bol is used as the procedure name. 

0 grouping 
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| alternation 

? last item is optional 

\e preceding any string means that the string will not match an input string if the input string is pre- 
ceded by an escape character (\). This is typically used for languages (like C) which can include 
the string delimiter in a string b escaping it. 

Unlike other regular expressions in the system, these match words and not characters. Hence something 
like "(tramp|steamer)flies?" would match "tramp”, "steamer", "trampflies", or "steamerflies". 

KEYWORD LIST 

The keyword list is just a list of keywords in the language separated by spaces. If the "oc" boolean is 
specified, indicating that upper and lower case are equivalent, then all the keywords should be specified in 
lower case. 

FILES 

/usr/lib/vgrindefs file containing terminal descriptions 

SEE ALSO 

vgrind(l), troff(l) 
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NAME 

ypfiles - the yellowpages database and directory structure 
DESCRIPTION 

The yellow pages (YP) network lookup service uses a database of dbm files in the directory hierarchy at 
/etc/yp . A dbm database consists of two files, created by calls to the dbm( 3X) library package. One has the 
filename extension .pag and the other has the filename extension .dir. For instance, the database named 
hosts.byname, is implemented by the pair of files hosts. byname. pag and hosts. byname. dir . A dbm database 
served by the YP is called a YP map . A YP domain is a named set of YP maps. Each YP domain is imple- 
mented as a subdirectory of letclyp containing the map. Any number of YP domains can exist. Each may 
contain any number of maps. 

No maps are required by the YP lookup service itself, although they may be required for the normal opera- 
tion of other parts of the system. There is no list of maps which YP serves - if the map exists in a given 
domain, and a client asks about it, the YP will serve it For a map to be accessible consistently, it must 
exist on all YP servers that serve the domain. To provide data consistency between the replicated maps, an 
entry to run ypxfr periodically should be made in lusr/lib/crontab on each server. More information on this 
topic is in ypxff(8). 

YP maps should contain two distinguished key-value pairs. The first is the key YP_LAST_MODIFIED, 
having as a value a ten-character ASCII order number. The order number should be the Unix time in 
seconds when the map was built. The second key is YP MASTER NAME, with the name of the YP mas- 
ter server as a value, makedbm generates both key-value pairs automatically. A map that does not contain 
both key-value pairs can be served by the YP, but the ypserv process will not be able to return values for 
"Get order number" or "Get master name" requests. In addition, values of these two keys are used by ypxfr 
when it transfers a map from a master YP server to a slave. If ypxfr cannot figure out where to get the map, 
or if it is unable to determine whether the local copy is more recent than the copy at the master, you must 
set extra command line switches when you run it. 

YP maps must be generated and modified only at the master server. They are copied to the slaves using 
ypxfr (8) to avoid potential byte-ordering problems among YP servers running on machines with different 
architectures, and to minimize the amount of disk space required for the dbm files. The YP database can be 
initially set up for both masters and slaves by using ypinit{%). 

After the server databases are set up, it is probable that the contents of some maps will change. In general, 
some ASCII source version of the database exists on the master, and it is changed with a standard text edi- 
tor. The update is incorporated into the YP map and is propagated from the master to the slaves by running 
letc/yp/Makefile . All Sun-supplied maps have entries in letclypl Makefile ; if you add a YP map, edit the 
this file to support the new map. The makefile uses makedbm to generate the YP map on the master, and 
yppush to propagate the changed map to the slaves, yppush is a client of the map ypservers , which lists all 
the YP servers. For more information on this topic, see yppush(8). 

SEE ALSO 

makedbm(8), ypinit(8), ypmake(8), ypxff(8), yppush(8), yppoll(8), ypserv(8), rpcinfo(8). 
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1 

1/2-inch tape drive 

tm — tapemaster, 337 
xt — Xylogics 472, 352 
1/4-inch tape drive 

ar — Archive 1/4-inch Streaming Tape Drive, 277 
st — Sysgen SC 4000 (Archive) Tape Drive, 333 thru 334 
10 Mb/s 3Com Ethernet interface — ec, 295 
10 Mb/s Sun-2 Ethernet interface — ie, 302 
10 Mb/s Sun-3/50 Ethernet interface — le, 313 thru3l4 

2 

2180 SMD Disk driver — ip, 309 thru 310 

3 

3Com 10 Mb/s Ethernet interface — ec, 295 

4 

450 SMD Disk driver — xy, 353 thru 354 
472 1/2-inch tape drive — xt, 352 

8 

8530 SCC serial comunications driver — zs, 355 

A 

a . out — assembler and link editor output, 357 
abort — generate fault, 133 
abs — integer absolute value, 134 
absolute value — abs, 134 
absolute value function — f abs, 205 
accept, 8 
access, 9 
access times of file 
change, 119 
accounting 

turn on or off, 10 
acct, 10 

a cos — trigonometric arccosine, 209 
actually move cursor — mv cur, 266 
Adaptec ST-506 disk driver — sd, 33 1 thru 332 
add character — addeh, 266 
add character — waddeh, 266 
add route ioctl— SIOCADDRT, 330 
add string — addstr, 266 
add string — waddstr, 266 


addeh — add character, 266 
addmntent — get filesystem descriptor file entry, 153 
addstr — add string, 266 
adjtime — ajdusttime, 11 
advise paging system, 120 
advisory lock 
apply, 29 
remove, 29 

alarm — schedule signal, 189 

aliases — sendmail aliases file, 361 

alphasort — sort directory, 174 

ANSI standard terminal emulation, 285 thru 289 

ANSI terminal emulation — cons, 285 thru 289 

ar — Archive 1/4-inch Streaming Tape Drive, 277 

ar — archive file format, 362 

arc — plot arc, 272 

archive file format — ar, 362 

argument lists 

varying length, 187 

argv 

get option letter — get opt, 190 
arp — Address Resolution Protocol, 278 thru 279 
arp ioctl 

SIOCDARP — delete arp entry, 278 
SIOCGARP — get arp entry, 278 
S IOCS ARP — set arp entry, 278 
ASCII to float — atof , 136 
ASCII to integer — atoi, 136 
ASCII to long — atol, 136 
asetime — date and time conversion, 139 
a sin — trigonometric arcsine, 209 
assembler output — a . out, 357 
assert — program verification, 135 
assign buffering to stream 

setbuf — assign buffering, 263 
setbuf f er — assign buffering, 263 
setlinebuf — assign buffering, 263 
async_daemon, 68 , 

at OOB mark? ioctl— SIOCATMARK, 336 

atan — trigonometric arctangent, 209 

atan2 — trigonometric arctangent, 209 

atof — ASCII to float, 136 

atoi — ASCII to integer, 136 

atol — ASCII to long, 136 

attributes of file f stat, 107 
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attributes of file lstat, 107 
attributes of file stat, 107 

1 

bcmp — compare byte strings, 137 
bcopy — copy byte strings, 137 
berknet information file — .netrc, 406 
Bessel functions 
j 0,208 
j 1,208 
jn, 208 
yO, 208 
yl, 208 
yn, 208 

binary I/O, buffered 

f read — read from stream, 252 
f rwite — write to stream, 252 
bind, 12 

bit clear local mode bits ioctl — TIOCLBIC, 346 
bit set local mode bits ioctl — TIOCLBIS, 346 
bit string functions 
ffs, 137 

bk — machine-machine communication line discipline, 280 
bk ioctl’s 

TIOCGETD — get line discipline, 280 
TIOCSETD — set line discipline, 280 
block signals, 97 
blocked signals 
release, 98 

box — draw box around window, 266 
brk, 13 

buffered binary I/O 

f read — read from stream, 252 
f rwite — write to stream, 252 
buffered I/O library functions 
introduction to, 247 thru 248 
buffering 

assign to stream — setbuf , 263 
assign to stream — setbuf fe r, 263 
assign to stream — setlinebuf , 263 
bwone — Sun-1 black and white frame buffer, 281 
bwtwo — Sun-3/Sun-2 black and white frame buffer, 282 
byte order 

convert between host and network, 212 
byte string functions 
bcmp, 137 
bcopy, 137 
bzero, 137 

bzero — zero byte strings, 137 

c 

C library functions 

introduction to, 127 thru 132 
cabs — Euclidean distance, 207 
ceil — ceiling of, 205 
cgone — Sun-1 color graphics interface, 283 
cgtwo — Sun-3/Sun-2 color graphics interface, 284 
change 

current working directory, 14 
root directory, 18 


change all window — touchwin, 266 
change data segment size, 13 
change file access times, 119 
change file mode, 15 
change file name — rename, 86 
change owner and group of file, 17 

change translation table entry ioctl — KIOCSETKEY, 311 
character 

get from stdin — get char, 254 
get from stream — fgetc, 254 
get from stream — get c, 254 
push back to stream — ungetc, 264 
put to stdin — put char, 259 
put to stream — f put c, 259 
put to stream — putc, 259 
character classification 
isalnum, 141 
isalpha, 141 
isascii, 141 
iscntrl, 141 
isdigit, 141 
isgraph, 141 
islower, 141 
i sprint, 141 
ispunct, 141 
isspace, 141 
i supper, 141 
isxdigit, 141 
character conversion 
toascii, 141 
tolower, 141 
toupper, 141 
chdir, 14 

check buffer state ioctl — GP 1 1 0_GET_GBUFFER_STATE, 
298 

checknews information file — . news rc, 410 
chmod, 15 
chown, 17 
chroot, 18 

circle — plot circle, 272 
clear — clear, 266 

clear break bit ioctl — TIOCCBRK, 345 

clear DTR ioctl — TIOCCDTR.345 

clear exclusive use of tty ioctl — TIOCEXCL, 344 

clear — clear, 266 

clear to bottom — clrtobot, 266 

clear to bottom of window — wclrtobot, 266 

clear to end of line — clrtoeol, 266 

clear to end of line — wclrtoeol, 266 

clear user table ioctl — NDIOCCLEAR, 323 

clear window — wclear, 266 

clearerr — clear error on stream, 250 

clearok — set clear flag for screen, 266 

close, 19 

close directory stream — closedir, 142 
close stream — fclose, 249 
closedir — close directory stream, 142 
closelog — close system log file, 184 
closepl — close plot device, 272 
clrtobot — clear to bottom, 266 
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cl rtoeol — clear to end of line, 266 
color graphics interface 

cgone — Sun-1 color graphics interface, 283 
cgtwo — Sun-3/Sun-2 color graphics interface, 284 
command 

return stream to remote, 223, 224 
compare byte strings — bcmp, 137 
compare string — strcmp, 182 
compare string — strncmp, 182 
compatibility library functions 
introduction to, 188 

compile regular expression — re_comp, 173 
concatenate strings — strcat, 182 
concatenate strings — st meat, 182 
connect, 20 
connected peer 

get name of, 42 
connection 

accept on socket, 8 
connections 

listen for on socket, 58 

cons — console driver/terminal emulator, 285 thru 289 
console I/O ioctl 
TIOCCONS, 285 
cont — continue line, 272 
control devices 
ioctl, 54 

control resource consumption — vlimit, 201 
control system log — closelog, 184 
control system log — openlog, 184 
control system log — syslog, 184 
control terminal 
hangup, 122 
convert 

between host and network byte order, 212 
host to network long — htonl, 212 
host to network short — hton s, 212 
network to host long — ntohl, 212 
network to host short — ntohs, 212 
convert character to ASCII — toascii, 141 
convert character to lower-case — tolower, 141 
convert character to upper-case — toupper, 141 
convert numbers to strings 
ecvt, 143 
fevt, 143 
f printf, 257 
gevt, 143 
printf, 257 
sprintf , 257 
convert strings to numbers 
atof, 136 
atoi, 136 
atol, 136 
f scanf, 261 
scanf, 261 
sscanf, 261 
convert time and date 
a setime, 139 
ctime, 139 
dysize, 140 
gmtime, 139 


convert time and date, continued 
localtime, 139 
timezone, 139 

copy byte strings — bcopy, 137 
copy strings — strepy, 182 
copy strings — strnepy, 182 
core — memory image file format, 363 
cos — trigonometric cosine, 209 
cosh — hyperbolic cosine, 210 
cpio — cpio archive format, 364 
creat, 21 
create directory, 60 
create file — open, 69 

create interprocess co mm unication channel — pipe, 71 
create interprocess communication endpoint, 104 
create name for temporary file — tmpnam, 198 
create new process, 30 
create new window — newwin , 266 
create pair of connected sockets, 106 
create special file, 62 
create subwindow — subwin , 266 
create symbolic link, 112 
create unique file name — mktemp, 164 
ermode — set ebreak mode, 266 
orontab — periodic jobs table, 365 
crypt — DES encryption, 138 
ctime — date and time conversion, 139 
current directory 
change, 14 

get pathname — getwd, 158 
current host 

get identifier of, 37 

D 

daemons 

network file system, 68 
data segment size 
change, 13 

datatypes — types, 445 
database functions 
dbminit, 268 
delete, 268 
fetch, 268 
fir st key, 268 
nextkey, 268 
store, 268 

database library functions 
ldbm option, 268 

date 

and time, get, 52 
and time, set, 52 
date and time 

get — time, 196 
get — ftime, 196 
date and time conversion 
asetime, 139 
ctime, 139 
dysize, 140 
gmtime, 139 
localtime, 139 
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date and time conversion, continued 
timezone, 139 
dbminit — open database, 268 
debugging support — assert, 135 
delch — delete character, 266 
delete arp entry ioctl — SIOCDARP, 278 
delete character — delch, 266 
delete character from window — wdelch, 266 
delete datum and key — delete, 268 
delete descriptor, 19 
delete directory entry — unlink, 117 
delete directory — rmdir, 88 
delete — delete datum and key, 268 
delete line — deleteln, 266 
delete line from window — wdeleteln, 266 
delete route ioctl— SIOCDELRT, 330 
delete window — delwin, 266 
deleteln — delete line, 266 
delwin — delete window, 266 
demount file system — unmount, 118 
des — DES encryption chip interface, 290 thru 291 
DES encryption 
crypt, 138 
encrypt, 138 
set key, 138 
descriptors 

close, 19 
delete, 19 
dup, 23 
dup2, 23 
f cntl, 27 

getdtablesize, 34 
select, 89 

DE s I OCBLOCK — process block, 290 
DE S I OCCHUNK — process 8 bytes, 290 
DESIOCGETIVEC — get init vector, 290 
DESI OCGETKEY — get des mode, 290 
DESIOCSETIVEC — set init vector, 290 
DES I OCSETKEY — set des mode, 290 
device control 
ioctl, 54 

devices, introduction to, 275 thru 276 
dir — directory format, 366 
directory 

change current, 14 
change root, 18 
delete — rmdir, 88 
erase — rmdir, 88 
get entries, 32 
make, 60 

remove — rmdir, 88 
scan, 174 

directory operations 
closedir, 142 
opendir, 142 
readdir, 142 
rewinddir, 142 
seekdir, 142 
telldir, 142 

disable file system quotas — setquota, 93 
disk control operations — dkio, 292 thru 293 


disk driver 

sd — Adaptec ST-506, 331 thru 332 
ip — Interphase, 309 thru 310 
si — Sun SCSI, 331 thru 332 
xy — Xylogics, 353 thru 354 
disk quotas, 76 

dkio — disk control operations, 292 thru 293 
DKIOCGGEOM — get disk geometry, 293 
DKI OCGPART — get disk partition info, 293 
DKIOCINFO — get disk info, 293 
DKIOCSGEOM — set disk geometry, 293 
DKIOCSPART — set disk partition info, 293 
domain 

get name of current, 33 
set name of current, 33 
draw box around window — box, 266 
drum — paging device, 294 
dump — incremental dump format, 368 
dup, 23 
dup2, 23 

duplicate descriptor, 23 

dysize — date and time conversion, 140 

E 

E2BIG error number, 1 
EACCES error number, 2 
EADDRINUSE error number, 4 
EADDRNOTAVAIL error number, 4 
EAFNOSUPPORT error number, 3 
E AGAIN error number, 1 
EALREADY error number, 3 
EBADF error number, 1 
EBUSY error number, 2 
ec — 3Com 10 Mb/s Ethernet interface, 295 
ECHILD error number, 1 
echo — set echo mode, 266 
ECONNABORTED error number, 4 
ECONNREFUSED error number, 4 
ECONNRESET error number, 4 
ecvt — convert number to ASCII, 143 
edata — end of program data, 144 
EDESTADDRREQ error number, 3 
EDOM error number, 3 
EDQUOT error number, 5 
EEXIST error number, 2 
EFAULT error number, 2 
EFBIG error number, 2 
effective group ID 
set, 94, 177 

effective group identity 
get, 35 

effective user ID 
get, 53 
set, 95, 177 

EHOSTDOWN error number, 4 
EHOSTUNREACH error number, 4 
E INPROGRESS error number, 3 
EINTR error number, 1 
EINVAL error number, 2 
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El O error number, 1 

El SCONN error number, 4 

El SD IR error number, 2 

ELOOP error number, 4 

EMF I LE error number, 2 

EMLINK error number, 3 

EMSGSIZE error number, 3 

enable file system quotas — set quota, 93 

ENAMETOOLONG error number, 4 

encrypt — DES encryption, 138 

encryption 

crypt, 138 
encrypt, 138 
setkey, 138 

encryption chip — des, 290 thru 291 

end — end of program, 144 

end locations in program, 144 

end standout mode — standend, 266 

end standout mode — wstandend, 266 

end window modes — endwin, 266 

endf sent — get file system descriptor file entry, 150 

endgrent — get group file entry, 151 

endhostent — get network host entry, 214 

endmntent — get filesystem descriptor file entry, 153 

endnetent — get network entry, 216 

endnetgrent — get network group entry, 217 

endprotoent — get protocol entry, 218 

endpwent — get password file entry, 157 

endrpcent — get rpc entry, 219 

endservent — get service entry, 220 

endwin — end window modes, 266 

ENETDOWN error number, 4 

ENETFESET error number, 4 

ENETUNREACH error number, 4 

ENFI LE error number, 2 

ENOBUFS error number, 4 

ENODEV error number, 2 

ENOENT error number, 1 

ENOEXEC error number, 1 

ENOMEM error number, 2 

ENOPROTOOPT error number, 3 

ENOSPC error number, 2 

ENOTBLK error number, 2 

ENOTCONN error number, 4 

ENOTDIR error number, 2 

ENOTEMPTY error number, 4 

ENOTSOCK error number, 3 

ENOTTY error number, 2 

enquire stream status 

clearerr — clear error on stream, 250 
f eof — enquire EOF on stream, 250 
f error — inquire error on stream, 250 
f ileno — get stream descriptor number, 250 
environ — user environment, 370 
en vi ron — execute file, 145 
environment 

get value — getenv, 149 
ENXIO error number, 1 
EOPNOTSUPP error number, 3 


EPERM error number, 1 

EPFNOSOPP ORT error number, 3 

EPIPE error number, 3 

EPROTONOSUPPORT error number, 3 

EPROTOTYPE error number, 3 

ERANGE error number, 3 

erase — erase, 266 

erase directory entry — unlink, 117 

erase directory — rmdir, 88 

erase — erase, 266, 272 

erase window — we rase, 266 

EREMOTE error number, 5 

EROFS error number, 3 

errno — system error messages, 169 

error messages, 169 

ESHUTDOWN error number, 4 

ESOCKTNOSUPPORT error number, 3 

ESPIPE error number, 3 

ESRCH error number, 1 

E STALE error number, 5 

etext — end of program text, 144 

Ethernet controller 

ec — 10 Mb/s 3Com Ethernet interface, 295 
ie — Sun-2 Ethernet interface, 302 
le — 10 Mb/s LANCE Ethernet interface, 313 thru 314 
ETIMEDOUT error number, 4 
ETXTBSY error number, 2 
Euclidean distance functions 
cabs, 207 
hypot, 207 

EWOULDBLOCK error number, 3 
EXDEV error number, 2 
execl — execute file, 145 
execle — execute file, 145 
execlp — execute file, 145 
execute file, 24, 145 
environ, 145 
execl, 145 
execle, 145 
execlp, 145 
execv, 145 
execvp, 145 

execute regular expression — re_exec, 173 
execution 

suspend for interval, 181 
execution profile 
prepare, 165 

execv — execute file, 145 
execve, 24 

execvp — execute file, 145 
exit, 26 

exit — terminate process, 147 
exp — exponential function, 204 
exponent and mantissa 
split into, 148 

exponential function — exp, 204 
exportf s — exported NFS file systems, 370 
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f abs — absolute value, 205 
f b — Sun console frame buffer driver, 296 
f bio — frame buffers general properties, 297 
fchmod, 15 
fchown, 17 

f close — • close stream, 249 
fcntl, 27 

f cntl — file control options, 373 
f cvt — convert number to ASCII, 143 
f dopen — associate descriptor, 251 
f eof — enquire EOF on stream, 250 
f error — inquire error on stream, 250 
fetch — retrieve datum under key, 268 
f flush — flush stream, 249 
f f s — find first one bit, 137 
f getc — get character from stream, 254 
f get s — get string from stream, 255 
file 

create new, 21 

create temporary name — tmpnam, 198 
determine accessibility of, 9 
execute, 24 
make hard link to, 57 
synchronize state, 31 
file attributes f stat, 107 
file attributes 1 stat, 107 
file attributes stat, 107 
file control, 27 

file control options — fcntl, 373 
file lock 

apply advisory, 29 
remove advisory, 29 
file position 
move, 59 
file system 

access, 9 

chdir, 14 

chmod, 15 

chown, 17 

chroot, 18 

create file — open, 69 

delete directory entry — unlink, 1 17 

delete directory — rmdir, 88 

unmount — demount file system, 118 

erase directory entry — unlink, 1 17 

erase directory — rmdir, 88 

fchmod, 15 

fchown, 17 

flock, 29 

ftruncate, 115 

get file descriptor entry, 150 

get di rent ries, 32 

link, 57 

lseek, 59 

mkdir, 60 

mknod, 62 

mount, 64 

mounted table — mtab, 404 
open, 69 
readlink, 82 


file system, continued 

remove directory entry — unlink, 117 

remove directory — rmdi r, 88 

rename file — rename, 86 

setquota, 93 

symlink, 112 

tell, 59 

truncate, 115 

umask, 116 

unmount — demount file system, 118 
utimes, 119 

file system format — fs, 374 
file system statistics — fstatfs, 109 
file system statistics — statf s, 109 
file times 

set — utime, 200 
filename 

change — rename, 86 
f ileno — get stream descriptor number, 250 
filesystem descriptor 
get file entry, 153 

fileystem static information — f stab, 377 
find first key — firstkey, 268 
find first one bit — f f s, 137 
find name of terminal, 186 
find next key — nextkey, 268 
FIOASYNC — set/clear async I/O, 276 
FIOCLEX — set exclusive use on fd, 276 
FIOGETOWN — get file owner, 276 
FIONBIO — set/clear non-blocking I/O, 276 
FIONCLEX — remove exclusive use, 276 
FIONREAD — get # bytes to read, 276 
FIOSETOWN — set file owner, 276 
firstkey — find first key, 268 
floating point 

i sinf — test infinite value, 161 
i snan — test not a number, 161 
flock, 29 

floor — floor of, 205 

flush buffers ioctl— TIOCFLUSH, 345 

flush stream — f flush, 249 

f open — open stream, 251 

fork, 30 

format of memory image file — core, 363 
formatted input conversion 

f scanf — convert from stream, 261 
scanf — convert from stdin, 261 
s scanf — convert from string, 261 
formatted write 

f printf — format to stream, 257 
printf — format to stdout, 257 
sprintf — format to string, 257 
f printf — format to stream, 257 
f putc — put character on stream, 259 
f puts — put string to stream, 260 
frame buffer 

bwone — Sun-1 black and white frame buffer, 281 
bwtwo — Sun-3/Sun-2 black and white frame buffer, 282 
f read — read from stream, 252 

free Static block ioctl — GPlIO_FREE_STATIC_BLOCK, 
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298 

f reopen — reopen stream, 251 

frexp — split into mantissa and exponent, 148 

f s — file system format, 374 

fscanf — convert from stream, 261 

f seek — seek on stream, 253 

f s tab — fileystem static information, 377 

f s tat — obtain file attributes, 107 

f statf s — obtain file system statistics, 109 

f sync, 31 

ft ell — get stream position, 253 
ft ±me — get date and time, 196 
f tpusers — ftp prohibited users list, 379 
ftruncate, 115 
full-duplex connection 
shut down, 96 

f write — write to stream, 252 

G 

gamma — log gamma, 206 
gather write — writev, 125 
gcd — multiple precision GCD, 270 
gc vt — convert number to ASCII, 143 
generate fault — abort, 133 
generate random numbers 

initstate — random number routines, 172 
random — generate random number, 172 
set state — random number routines, 172 
s random — generate random number, 172 
generate random numbers — rand, 194 
generate random numbers — s rand, 194 
generic disk control operations — dkio, 292 thru 293 
generic operations 

gather write — writev, 125 
ioctl, 54 
read, 80 

scatter read — readv, 80 
write, 125 

get # bytes to read ioctl — FIONREAD, 276 
get (y,x) co-ordinates — getyx, 266 
get arp entry ioctl — SIOCGARP, 278 
get character — get ch, 266 

get character at current (y,x) co-ordinates — inch, 266 

get character at current (y,x) in window — winch, 266 

get character from stream — fgetc,254 

get character from stream — getc, 254 

get character through window — wgetch, 266 

get console I/O ioctl — TIOCCONS, 285 

get current domain name, 33 

get current working directory pathname — getwd, 158 

get date and time, 52, 196 

get date and time — ftime, 196 

get des mode ioctl — DESIOCGETKEY, 290 

get disk geometry ioctl — DKIOCGGEOM, 293 

get disk info ioctl— DKIOC INFO, 293 

get disk partition info ioctl — DKIOCGPART, 293 

get entries from name list — nlist, 167 

get environment value — getenv, 149 

get file owner ioctl — FIOGETOWN, 276 


get file system descriptor file entry, 150 
get filesystem descriptor file entry 
addmntent, 153 
endmntent, 153 
getmntent, 153 
hasmntopt, 153 
setmntent, 153 
get group file entry 
endgrent, 151 
getgrent, 151 
getgrgid, 151 
getgrnam, 151 
setgrent, 151 

get high water mark ioctl — SIOCGHIWAT, 336, 348 

get ifnet address ioctl — SIOCGIFADDR, 303 

get ifnet flags ioctl — SIOCGIFFLAGS, 303 

get ifnet list ioctl — SIOCGIFCONF, 303 

get info on resource usage — vtimes, 202 

get init vector ioctl — DESIOCGETIVEC, 290 

get keyboard translatability ioctl — KIOCGTRANSABLE, 312 

get keyboard translation ioctl — KIOCGTRANS, 311 

get keyboard type ioctl — KIOCTYPE, 312 

get line discipline ioctl — TIOCGETD, 280, 338 

get local mode bits ioctl — TIOCLGET, 346 

get local special chars ioctl — TIOCGLTC.346 

get login name — getlogin, 152 

get long name — longname, 266 

get low water mark ioctl — SIOCGLOWAT, 336, 348 

get network entry, 216 

get network group entry, 217 

get network host entry, 214 

get network service entry, 220 

get option letter from argv — getopt, 190 

get options sockets, 51 

get p-p address ioctl — SIOCGIFDSTADDR, 303 
get parameters — gtty ioctl — T IOCGETP, 344 
get parent process identification, 44 
get password file entry 
endpwent, 157 
getpwent, 157 
getpwnam, 157 
getpwuid, 157 
getpwent, 157 

get position of stream — f tel 1, 253 

get process group of tty ioctl — TIOCGPGRP, 345 

get process identification, 44 

get process times — times, 197 

get protocol entry, 218 

get requested minor device ioctl — GPlIO_GET_REQDEV, 
298 

get restart count ioctl — GPlIO_GET_RESTART_COUNT, 
298 

get rpc program entry, 219 

get scheduling priority, 45 

get signal stack context, 100 

get special characters ioctl — TIOCGETC, 345 

get static block ioctl — GP1 IO_GET_STATIC_BLOCK, 298 

get string — get st r, 266 

get string from stdin — gets, 255 


459 - 



Index Continued 


get string from stream — f get s, 255 
get string through window — wgetstr, 266 
get tape status ioctl— MTIOCGET, 320 
get te rmin al capability — getcap, 266 
get terminal state — gtty, 195 
get translation state ioctl— KIOCGTRANS, 311 
get translation table entry ioctl — KIOCGETKEY, 311 
get true minor device ioctl — GP1 lO_GET_TRUMINORDEV, 
299 

get tty modes — gettmode, 266 
get user limits — ulimit, 199 
get word from stream — getw, 254 
getc — get character from stream, 254 
getcap — get te rmin al capability, 266 
getch — get character, 266 
get char — get character from stdin, 254 
getdirentries, 32 
getdomainname, 33 
getdtablesize, 34 
getegid, 35 

getenv — get value from environment, 149 
geteuid, 53 

getf sent — get file system descriptor file entry, 150 
getf sf ile — get file system descriptor file entry, 150 
getf s spec — get file system descriptor file entry, 150 
getf stype — get file system descriptor file entry, 150 
getgid, 35 

getgrent — get group file entry, 151 
getgrgid — get group file entry, 151 
getgrnam — get group file entry, 151 
getgroups, 36 

gethostbyaddr — get network host entry, 214 
gethostbyname — get network host entry, 214 
gethostent — get network host entry, 214 
gethostid, 37 
gethostname, 38 
getitimer, 39 

getlogin — get login name, 152 

getmntent — get filesystem descriptor file entry, 153 

getnetbyaddr — get network entry, 216 

getnetbyname — get network entry, 216 

getnetent — get network entry, 216 

getnetgrent — get network group entry, 217 

getopt — get option letter, 190 

getpagesize, 41 

getpass — read password, 155 

getpeername, 42 

getpgrp, 43 

getpid, 44 

getppid, 44 

getpriority, 45 

getprotobynumber — get protocol entry, 218 
getprotoent — get protocol entry, 218 
getpw — get name from uid, 156 
getpwent — get password file entry, 157 
getpwnam — get password file entry, 157 
getpwuid — get password file entry, 157 
getrlimit,46 


getrpcbyname — get rpc entry, 219 
getrpcbynumber — get rpc entry, 219 
getrpcent — get rpcice entry, 219 
getrusage, 48 

get s — get string from stdin, 255 

get servbyname — get service entry, 220 

get servbyport — get service entry, 220 

gets erven t — get service entry, 220 

getsockname, 50 

getsockopt, 51 

get st r — get string through, 266 

gettimeof day, 52 

gettmode — get tty modes, 266 

gettytab — terminal configuration data base, 380 

getuid, 53 

getw — get word from stream, 254 
getwd — get current working directory pathname, 158 
getyx — get (y,x) co-ordinates, 266 
gmtime — date and time conversion, 139 
GP 1 1 0_CHK_GP — restart GP, 298 
GP 1 X 0_FREE_STAT I C_BLOCK — free static block, 298 
GP1 IO_GET_GBUFFER_STATE — check buffer state, 298 
GP1 IO_GET_REQDEV — get requested minor device, 298 
GP1 IO_GET_RESTART_COUNT — get restart count, 298 
GP 1 1 0_GET_STAT I C_BLOCK — get static block, 298 
GP1 1 0_GET_TRUMI NORDEV — get true minor device, 299 
GP1 IO_PUT_INFO — pass framebuffer info, 298 
GP 1 1 0_RED I RECT_DEVFB — reconfigure fb, 298 
gpone — graphics processor interface, 298 thru 299 
graphics interface 
arc, 272 
circle, 272 
clasepl, 272 
cont, 272 
erase, 272 
label, 272 
line, 272 
linemod, 272 
move, 272 
openpl, 272 
point, 272 
space, 272 

graphics interface files — plot, 414 
graphics processor interface — gpone, 298 thru 299 
group access list 
get, 36 

initialize — initgroups, 159 
group entry 

get network, 217 
group — group file format, 383 
group file entry 
get, 151 
group ID 

set real and effective, 94 
group identity 
get, 35 

get effective, 35 
groups access list 
set, 91 

gtty — get terminal state, 195 
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H 

halt processor, 83 

hang up on lastclose ioctl — - TIOCHPCL, 341, 345 
hangup control terminal, 122 
hard link to file, 57 

hardware support, introduction to, 275 thru 276 
hasmntopt — get filesystem descriptor file entry, 153 
host 

get identifier of, 37 
host byte order 

convert to network, 212 
host entry 

get network, 214 
host name 
get, 38 
set, 38 

host phone numbers — phones, 413 
host s — host name data base, 384 
host s . equiv — trusted hosts list, 385 
htonl — convert network to host long, 212 
htons — convert host to network short, 212 
hyperbolic functions 
cosh, 210 
sinh, 210 
tanh, 210 

hypot — Euclidean distance, 207 

I 

I/O, buffered binary 

f read — read from stream, 252 
f rwite — write to stream, 252 
icmp — Internet Control Message Protocol, 300 thru 301 
identifier 

of current host, 37 

ie — Sun-2 10 Mb/s Ethernet interface, 302 
if — network interface general properties, 303 thru 304 
Ikon 10071-5 printer interface — vp, 349 
inch — get character at current (y,x) co-ordinates, 266 
incremental dump format — dump, 368 
indeterminate floating point values 
test for, 161 

index — find character in string, 182 

index strings — index, 182 

index strings — rindex, 182 

indirect system call, 1 14 

inet — Internet protocol family, 305 thru 306 

inet server database — servers, 426 

inet_addr — Internet address manipulation, 221 

inet_lnaof — Internet address manipulation, 221 

inet_makeaddr — Internet address manipulation, 221 

inet_netof — Internet address manipulation, 221 

inet_network — Internet address manipulation, 221 

inet_ntoa — Internet address manipulation, 221 

initgroups — initialize group access list, 159 

initialize group access list — initgroups, 159 

initialize screens — initscr, 266 

initiate 

connection on socket, 20 
initiate I/O to/from process, 256 


initscr — initialize screens, 266 
initstate — random number routines, 172 
innetgr — get network group entry, 217 
input conversion 

f scanf — convert from stream, 261 
scanf — convert from stdin, 261 
sscanf — convert from string, 261 
input stream 

push character back to — unget c, 264 
inquire stream status 

clearerr — clear error on stream, 250 
f eof — enquire EOF on stream, 250 
f error — inquire error on stream, 250 
f i 1 eno — get stream descriptor number, 250 
insch — insert character, 266 
insert character — insch, 266 
insert character in — win sch, 266 
insert element in queue — insque, 160 
insert line — insertln, 266 
insert line in — winsertln, 266 
insertln — insert line, 266 
insque — insert element in queue, 160 
integer absolute value — abs, 134 
Internet 

control message protocol — icmp, 300 thru 301 
protocol family — inet, 305 thru 306 
Protocol — ip, 307 thru 308 
to Ethernet address resolution — arp, 278 thru 279 
Transmission Control Protocol — tcp, 335, 336 
User Datagram Protocol — udp, 347, 348 
Internet address manipulation, 221 
Interphase SMD Disk driver — ip, 309 thru 310 
interprocess communication 
accept, 8 
bind, 12 
connect, 20 
getsockname, 50 
getsockopt, 51 
listen, 58 
pipe, 71 
recv, 84 
recvfrom, 84 
recvmsg, 84 
send, 90 
sendmsg, 90 
sendto, 90 
setsockopt, 51 
shutdown, 96 
socket, 104 
socketpair, 106 
interrupts 

release blocked signals, 98 
interval timers 
get, 39 
set, 39 

timerclear macro, 39 
timer cmp macro, 39 
timerisset macro, 39 
introduction 

C library functions, 127 thru 132 
compatibility library functions, 188 
mathematical library functions, 203 
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introduction, continued 

miscellaneous library functions, 265 
network library functions, 211 
standard I/O library functions, 247 thru 248 
system calls, 1 thru 7 
system error numbers, 1 thru 5 
to devices, 275 thru 276 
to hardware support, 275 thru 276 
to special files, 275 thru 276 
ioctl, 54 
ioctl’s fordes chip 

DESIOCBLOCK — process block, 290 
DESIOCCHUNK — process 8 bytes, 290 
DES I OCGET I VEC — get init vector, 290 
DES I OCGETKE Y — get des mode, 290 
DESIOCSETIVEC — set init vector, 290 
DES IOCSETKEY — set des mode, 290 
ioctl’s for disks 

DKI OCGGEOM — get disk geometry, 293 
DKX OCGP ART — get disk partition info, 293 
DKXOCINFO — get disk info, 293 
DKI OCSGEOM — set disk geometry, 293 
DKIOCSPART — set disk partition info, 293 
ioctl’s for files 

FIOASYNC — set/clear async I/O, 276 
FIOCLEX — set exclusive use on fd, 276 
FIOGETOWN get owner, 276 
FIONBIO — set/clear non-blocking I/O, 276 
FIONCLEX — remove exclusive use, 276 
F IONREAD — get # bytes to read, 276 
FIOSETOWN — set owner, 276 
ioctl’s for graphics processor 

GP1 IO_CHK_GP — restart GP, 298 
GP1 IO_FREE_STATIC_BLOCK— free static block, 298 
GP1 IO_GET_GBUFFER_STATE — check buffer state, 298 
GP1 1 0_GET_REQDEV — get requested minor device, 298 
GP1 IO_GET_RESTART_COUNT — get restart count, 298 
GP1 1 0_GET_S TAT I C_BLOCK — get static block, 298 
GP1 IO_GET_TRUMINORDEV — get true minor device, 299 
GP1 1 0_P UT_I NF 0 — pass framebuffer info, 298 
GP1 1 0_RED I RECT_DEVFB — reconfigure fb, 298 
ioctl’s for keyboards 

KIOCCMD — send a keyboard command, 312 
KIOCGETKEY — get translation table entry, 311 
KIOCGTRANS — get keyboard translation, 311 
K IOCGTRAN SABLE — get keyboard translatability, 312 
K IOCSETKEY — change translation table entry, 311 
KIOCTRANS — set keyboard translation, 311 
KIOCTRANSABLE — set keyboard translatability, 312 
KIOCTYPE — get keyboard type, 312 
ioct l’s for network disks 

NDI OCCLEAR — clear user table, 323 
NDI OCETHER — set ether address, 323 
NDIOCSAT — server at ipaddress, 323 
NDI OCSOFF — server off, 323 
NDI OCSON — server on, 323 
NDI OCUSER — set user parameters, 323 
NDI OCVER — version number, 323 
ioctl’s for sockets 

SIOCADDRT — add route, 330 
SIOCATMARK — at OOB mark?, 336 
SIOCDARP — delete arp entry, 278 
SIOCDELRT — delete route, 330 


ioctl’s for sockets, continued 

SIOCGARP — get arp entry, 278 
SIOCGHIWAT — get high water mark, 336, 348 
SIOCGIFADDR — get ifhet address, 303 
SIOCGIFCONF — get ifhet list, 303 
SIOCGIFDSTADDR — get p-p address, 303 
SIOCGIFFLAGS — get ifnet flags, 303 
SIOCGLOWAT — get low water mark, 336, 348 
SIOCSARP — set arp entry, 278 
SIOCSHIWAT — set high water mark, 336, 348 
S IOCS IFADDR — set ifnet address, 303 
S I OCS IFDSTADDR — set p-p address, 303 
SIOCSIFFLAGS — set ifnet flags, 303 
SIOCSLOWAT — set low water mark, 336, 348 
ioctl’s for tapes 

MTIOCGET — get tape status, 320 
MTIOCTOP — tape operation, 319 
ioctl’s for terminals 

TIOCCBRK — clear break bit, 345 
TIOCCDTR — clear DTR, 345 
TIOCCONS — get console I/O, 285 
TIOCEXCL — clear exclusive use of tty, 344 
TIOCFLUSH — flush buffers, 345 
TIOCGETC — get special characters, 345 
TIOCGETD — get line discipline, 280, 338 
TIOCGETP — get parameters — gtty, 344 
TIOCGLTC — get local special chars, 346 
TIOCGPGRP — get process group of tty, 345 
TIOCHPCL — hang up on last close, 341, 345 
TIOCLBIC — bit clear local mode bits, 346 
TIOCLBI S — bit set local mode bits, 346 
TIOCLGET — get local mode bits, 346 
TIOCLSET — set local mode bits, 346 
TIOCNOTTY — void tty association, 338 
TIOCNXCL — remove exclusive use of tty, 344 
TIOCPKT — set/clear packet mode (pty), 328 
TIOCREMOTE — remote input editing, 328 
TIOCSBRK — set break bit, 345 
TIOCSDTR — set DTR, 345 
TIOCSETC — set special characters, 345 
TIOCSETD — set line discipline, 280, 338 
TIOCSETN — set exclusive use of tty, 344 
TIOCSETP — set parameters — gtty, 344 
TIOCSLTC — set local special chars, 346 
TIOCSPGRP — set process group of tty, 345 
TIOCSTART — start output (like control-Q), 328 
TIOCSTI — simulate terminal input, 345 
TIOCSTOP — stop output (like control-S), 328 
ip — Internet Protocol, 307 thru 308 
ip — Interphase SMD Disk driver, 309 thru 310 
isalnum — is character alphanumeric, 141 
i salpha — is character letter, 141 
isascii — is character ASCII, 141 
i satty — test if device is terminal, 186 
i scntrl — is character control, 141 
i sdigit — is character digit, 141 
i sgraph — is character graphic, 141 
isinf — test infinite value, 161 
i slower — is character lower-case, 141 
i snan — test not a number, 161 
i sprint — is character printable, 141 
ispunct — is character punctuation, 141 
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space — is character whitespace, 141 
issue shell command — system, 185 
i supper — is character upper-case, 141 
isxdigit — is character hex digit, 141 
itom — integer to multiple precision, 270 

J 

j 0 — Bessel function, 208 
jl — Bessel function, 208 
jn — Bessel function, 208 

K 

kb — Sun keyboard, 311 thru 312 
kbd — keyboard translation tables, 386 
keyboard translation tables — kbd, 386 
kill, 55 
killpg-, 56 

KIOCCMD — send a keyboard command, 312 
KIOCGETKEY — get translation table entry, 311 
KI OCGTRANS — get keyboard translation, 311 
KIOCGTRANS — get translation state, 311 
KIOCGTRAN SABLE — get keyboard translatability, 312 
KIOCSETKEY — change translation table entry, 311 
KIOCTRANS — set keyboard translation, 311 
K 1 OCTRAN SABLE — set keyboard translatability, 312 
KIOCTYPE — get keyboard type, 312 
kmem — kernel memory space, 316 

L 

label — plot label, 272 

LANCE 10 Mb/s Ethernet interface — le, 313 thru 314 

last locations in program, 144 

la st log — login records, 447 

ldexp — split into mantissa and exponent, 148 

le — Sun-3/50 10 Mb/s Ethernet interface, 313 thru 314 

leaveok — set leave flag for window, 266 

library file format — ar, 362 

library functions 

introduction to C, 127 thru 132 
introduction to compatibility, 188 
introduction to mathematical, 203 
introduction to miscellaneous, 265 
introduction to network, 211 
introduction to standard I/O, 247 thru 248 
limits 

get for user — ulimit, 199 
set for user — ulimit, 199 
line discipline — bk, 280 
line discipline ioctl’s 

T X OCGETD — get line discipline, 280 
T I OCSETD — set line discipline, 280 
line — plot line, 272 
linemod — set line style, 272 
link, 57 

make symbolic, 112 
read value of symbolic, 82 
link editor output — a. out, 357 
listen, 58 

lo — software loopback network interface, 315 


localtime — date and time conversion, 139 
lock 

apply advisory, 29 
remove advisory, 29 
log — natural logarithm, 204 
log ga mm a function — gamma, 206 
loglO — logarithm, base 10, 204 
logarithm, base 10 — logl 0, 204 
logarithm, natural — log, 204 
login environment — environ, 370 
login name 

get — getlogin, 152 
login records 

lastlog file, 447 
utmp file, 447 
wtmp file, 447 

longjmp — non-local goto, 175 
longname — get long name, 266 
lseek, 59 

1st at — obtain file attributes, 107 

M 

machine-machine communication line discipline — bk, 280 
madd — multiple precision add, 270 
magnetic tape interface — mtio, 319 thru 320 
magnetic tape ioctl’s 

MTIOCGET — get tape status, 320 
MTIOCTOP — tape operation, 319 
make directory, 60 
make hard link to file, 57 

make interprocess communication channel — pipe, 71 
make interprocess communication endpoint, 104 
make name for temporary file — tmpnam, 198 
make pair of connected sockets, 106 
make screen look like window — wrefresh, 266 
make special file, 62 
make symbolic link, 1 12 
make unique file name — mktemp, 164 
manipulate disk quotas, 76 
manipulate Internet addresses, 221 
mantissa and exponent 
split into, 148 
map memory pages, 63 
mask 

set current signal, 99 
mathematical functions 
acos, 209 
asin, 209 
atan, 209 
atan2, 209 
cabs, 207 

ceil — ceiling of, 205 
cos, 209 
cosh, 210 

exp — exponential, 204 
f abs — absolute value, 205 
floor — floor of, 205 
gamma, 206 
hypot, 207 
jO, 208 
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mathematical functions, continued 
j 1, 208 
j n, 208 

1 og — natural logarithm, 204 
loglO — logarithm, base 10, 204 
pow — raise to power, 204 
s in, 209 
sinh, 210 

s <qrt — square root, 204 
t an, 209 
t anh, 210 
y 0,208 
y 1,208 
yn, 208 

mathematical library functions 
introduction to, 203 
mbio — Multibus I/O space, 316 
mbmem— Multibus memory space, 316 
mdiv — multiple precision divide, 270 
mem — main memory space, 316 
memory image file format — core, 363 
memory images 

kmem — kernel memory space, 316 
mbio — Multibus I/O space, 316 
mbmem — Multibus memory space, 316 
mem — main memory space, 316 
virtual — virtual address space, 316 
vmel6 — VMEbus 16-bit space, 316 
vmel 6dl 6 — VMEbus address space, 316 
vmel6d32 — VMEbus address space, 316 
vme24 — VMEbus 24-bit space, 316 
vme2 4 dl 6 — VMEbus address space, 316 
vme24d32 — VMEbus address space, 316 
vme32dl 6 — VMEbus address space, 316 
vme32d32 — VMEbus address space, 316 
memory management 
t>rk, 13 

getpagesize, 41 
mmap, 63 
sbrk, 13 
unmap, 66 
message 

receive from socket, 84 
send from socket, 90 
messages 

system error, 169 
system signal, 170 

min — multiple precision decimal input, 270 
miscellaneous library functions 
introduction to, 265 
mkdi x, 60 
mknod, 62 

mktemp — make unique file name, 164 
mmap, 63 

modf — split into mantissa and exponent, 148 
moncontrol — make execution profile, 165 
moni-tor — make execution profile, 165 
monochrome frame buffer — bwone, 281 
monochrome frame buffer — bwtwo, 282 
mons-tartup — make execution profile, 165 
mount, 64 

mounted file system table — mtab, 404 


mouse — Sun mouse, 317 
mout — multiple precision decimal output, 270 
move file position, 59 
move — move to (y,x), 266, 272 
moveto(y,x) — move, 266 
msqrt — multiple precision exponential, 270 
msub — multiple precision subtract, 270 
mtab — mounted file system table, 404 
mti — Systech MTI-800/1600 multi-terminal interface, 318 
mtio — UNIX magnetic tape interface, 319 thru 320 
MTIOCGET — get tape status, 320 
MTIOCTOP — tape operation, 319 
mult — multiple precision multiply, 270 
multiple precision integer arithmetic 
gcd, 270 
itom, 270 
madd, 270 
mdiv, 270 
min, 270 
mout, 270 
msqrt, 270 
msub, 270 
mult, 270 
pow, 270 
rpow, 270 
sdiv, 270 

mvcur — actually move cursor, 266 

N 

name list 

get entries from, 167 
name of terminal 
find, 186 

name termination handler — on_exit, 168 
natural logarithm — log, 204 
nd — network disk driver, 321 thru 323 
NDIOCCLEAR — clear user table, 323 
NDIOCETHER — set ether address, 323 
NDIOCSAT — server at ipaddress, 323 
NDIOCSOFF — server off, 323 
NDIOCSON — server on, 323 
NDI OCOSER — set user parameters, 323 
NDIOCVER — version number, 323 
net group — network groups list, 405 
. netrc — berknet information file, 406 
network byte order 

convert to host, 212 
network disk ioctl’s 

NDIOCCLEAR — clear user table, 323 
NDIOCETHER — set ether address, 323 
NDIOCSAT — server at ipaddress, 323 
NDIOCSOFF — server off, 323 
NDIOCSON — server on, 323 
NDIOCUSER — set user parameters, 323 
NDIOCVER — version number, 323 
network entry 
get, 216 

network file system 
mount, 64 

network file system daemons, 68 
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network group entry 
get, 217 

network host entry 
get, 214 

network interface ioctl’s 

SIOCGIFADDR — get ifhet address, 303 
SIOCGIFCONF — get ifhet list, 303 
SIOCGIFDSTADDR — get p-p address, 303 
SIOCGIFFLAGS — get ifhet flags, 303 
SIOCSIFADDR — set ifnet address, 303 
SIOCSIFDSTADDR — set p-p address, 303 
SIOCSIFFLAGS — set ifhet flags, 303 
network interface tap protocol — nit, 324 thru 326 
network library functions 
introduction to, 211 

network loopback interface — lo, 3 15 
network news file formats — news, 408 
network packet routing device — routing, 330 
network service entry 
get, 220 

networks — network name data base, 407 
news — USENET network news file formats, 408 
newwin — create new window, 266 
nextkey — find next key, 268 
NFS exported file systems — exportfs, 372 
nf smount — see mount, 64 
nf ssvc, 68 

nice — set program priority, 192 

nit — network interface tap protocol, 324 thru 326 

nl — set newline mapping, 266 

nl ist — get entries from name list, 167 

nocrmode — unset cbreak mode, 266 

noecho — unset echo mode, 266 

non-local goto 

non-local goto — long jmp, 175 
non-local goto — set jmp, 175 
nonl — unset newline mapping, 266 
no raw — unset raw mode, 266 
nt ohl — convert network to host long, 212 
nt ohs — convert host to network short, 212 
null — null device, 327 
null-terminated strings 

compare — strcmp, 182 
compare — strncmp, 182 
concatenate — strcat, 182 
concatenate — strncat, 182 
copy — strcpy, 182 
copy — strncpy, 182 
index — index, 182 
index — rindex, 182 
reverse index — rindex, 182 
numbers 

convert from strings, 136 
convert to strings, 143 

o 

on_exit — name termination handler, 168 
open, 69 

open database — dbminit, 268 
open directory stream — opendir, 142 


open stream — f open, 251 
opendir — open directory stream, 142 
openlog — initialize system log file, 184 
openpl — open plot device, 272 
optarg — get option letter, 190 
optind — get option letter, 190 
option letter 

get from argv — getopt, 190 
options on sockets 
get, 51 
set, 51 

output conversion 

fprintf — convert to stream, 257 
print f — convert to stdout, 257 
sprintf — convert to string, 257 
overlay — overlay winl on win2, 266 
overlay winl on win2 — overlay, 266 
overwrite — overwrite winl on win2, 266 
overwrite winl on win2 — overwrite, 266 

P 

packet routing device — routing, 330 
packet routing ioctl’s 

SIOCADDRT — add route, 330 
SIOCDELRT — delete route, 330 
page size 
get, 41 

paging device — swapon, 111, 294 
paging system 
advise, 120 

parent process identification 
get, 44 

pass framebuffer info ioctl — GPlIO_PUT_INFO, 298 

pas swd — password file, 411 

password 

read — getpass, 155 
password file 

get entry — endpwent, 157 
get entry — getpwent, 157 
get entry — getpwnam, 157 
get entry — getpwuid, 157 
get entry — setpwent, 157 
pause — stop until signal, 193 
pclose — close stream to process, 256 
peer name 
get, 42 

periodic jobs table — crontab, 365 
per ror — system error messages, 169 
phone s — remote host phone numbers, 413 
pipe, 71 

plot — graphics interface files, 414 

point — plot point, 272 

popen — open stream to process, 256 

position of directory stream — telldir, 142 

pow — raise to power, 204, 270 

power function — pow, 204 

prepare execution profile 

moncontrol — make execution profile, 165 
monitor — make execution profile, 165 
monstartup — make execution profile, 165 
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primitive system data types — types, 445 
printable version of control — un Ctrl, 266 
pr intcap — printer capability data base, 415 
printer interface 

vp — Ikon 10071-5 Versatec parallel printer interface, 349 
vpc — Systech VPC-2200 Versatec/Centronics interface, 350 
print f — format to stdout, 257 
printf to window — printw, 266 
printf to window — wprintw , 266 
printw — printf to window, 266 
priority 
get, 45 
set, 45 

priority of program 
set — nice, 192 
process 

create, 30 

initiate I/O to/from, 256 
send signal to, 55 
terminate, 26 

terminate and cleanup — exit, 147 
process 8 bytes ioctl — DESIOCCHUNK, 290 
process block ioctl — DESIOCBLOCK, 290 
process group 
get, 43 

send signal to, 56 
process identification 
get, 44 

process times 

get — times, 197 
process tracing — ptrace, 73 thru 75 
processes 

software signals — sigvec, 101 thru 103 
processes and protection 
execve, 24 
exit, 26 
fork, 30 

getdomainname, 33 
getegid, 35 
geteuid, 53 
getgid, 35 
getgroups, 36 
gethostid, 37 
gethostname, 38 
getpgrp, 43 
getpid, 44 
getppid, 44 
getuid, 53 
ptrace, 73 thru 75 
setdomainname, 33 
setgroups, 91 
sethostname, 38 
setpgrp, 92 
setregid, 94 
setreuid, 95 
vfork, 121 
vhangup, 122 
wait, 123 
wait3, 123 
processes group 
set, 92 
prof il, 72 


profile 

prepare execution, 165 
program priority 

set — nice, 192 

program verification — assert, 135 
protocol entry 
get, 218 

protocols — protocol name data base, 417 
psignal — system signal messages, 170 
ptrace, 73 thru 75 

pty — pseudo terminal driver, 328 thru 329 

push character back to input stream — ungetc, 264 

put character to stdout — put char, 259 

put character to stream — f putc, 259 

put character to stream — putc, 259 

put string to stdout — puts, 260 

put string to stream — fputs, 260 

put word to stream — putw, 259 

putc — put character on stream, 259 

put char — put character on stdout, 259 

puts — put string to stdout, 260 

putw — put word on stream, 259 

Q 

qsort — quicker sort, 171 
queue 

insert element in — insque, 160 
remove element from — remque, 160 
quicker sort — qsort, 171 
quota, 76 

quotas for file system — setquota, 93 

R 

rand — generate random numbers, 194 
random — generate random number, 172 
random number generator 

initstate — random number routines, 172 
random — generate random number, 172 
set state — random number routines, 172 
s random — generate random number, 172 
random number generator — rand, 194 
random number generator — srand, 194 
rasterfile, 418 
raw — set raw mode, 266 
rcmd — execute command remotely, 223 
re_comp — compile regular expression, 173 
re_exec — execute regular expression, 173 
read, 80 

read directory stream — readdir, 142 
read formatted 

f scanf — convert from stream, 261 
scanf — convert from stdin, 261 
sscanf — convert from string, 261 
read from stream — f read, 252 
read password — getpass, 155 
read scattered — readv, 80 
read/write pointer 
move, 59 

readdir — read directory stream, 142 
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readlink, 82 

readnews information file — . newsrc, 410 
real group ID 
set, 94, 177 
real user ID 
get, 53 
set, 95, 177 
reboot, 83 

receive message from socket, 84 

reconfigure fb ioctl— GP1I0_REDIRECT_DEVFB, 298 
recv, 84 
recvf rom, 84 
recvmsg, 84 

refresh current screen — refresh, 266 
refresh — refresh current screen, 266 
regular expressions 

compile — re_comp, 173 
execute — re_exec, 173 
release blocked signals, 98 
remote command 

return stream to, 223, 224 
remote — remote host descriptions, 419 
remote host phone numbers — phones, 413 
remote input editing ioctl — TIOCREMOTE, 328 
remove directory entry — unlink, 117 
remove directory — rmdir, 88 
remove element from queue — remque, 160 
remove exclusive use ioctl — FIONCLEX, 276 
remove exclusive use of tty ioctl — TIOCNXCL, 344 
remove file system — unmount, 118 
remque — remove element from queue, 160 
rename file — rename, 86 
reopen stream — f reopen, 251 
reposition stream 
f seek, 253 
ftell, 253 
rewind, 253 

reset tty flags to stored value — resetty, 266 
resetty — reset tty flags to stored value, 266 
resource consumption 

control — vlimit, 201 
resource control 

getrlimit, 46 
getrusage, 48 
setrlimit,46 
resource controls 

file system quotas — setquota, 93 
getpriority, 45 
quota, 76 
setpriority, 45 
resource usage 

get info — vtimes, 202 
resource utilization 

get information about, 48 
restart GP ioctl — GPlIO_CHK_GP, 298 
retrieve datum under key — f et ch, 268 
return stream to remote command, 223, 224 
return to saved environment — longjmp, 175 
reverse index strings — rindex, 182 
rewind directory stream — rewinddir, 142 


rewind — rewind stream, 253 
rewind stream — rewind, 253 
rewinddir — rewind directory stream, 142 
rexec — return stream to remote command, 224 
rindex — find character in string, 182 
rmdir — remove directory, 88 
rmtab — remote mounted file system table, 421 
root directory 
change, 18 

routing — local network packet routing, 330 
routing ioctl’s 

SIOCADDRT — add route, 330 
SIOCDELRT — delete route, 330 
rpc entry 
get, 219 

rpc program entry 
get, 219 

rpc — rpc name data base, 422 
rpow — multiple precision exponential, 270 
rresvport — get privileged socket, 223 
ruserok — authenticate user, 223 

s 

save stack environment — set jmp, 175 
savetty — stored current tty flags, 266 
sbrk, 13 

scan directory — alpha sort, 174 
scan directory — scandir, 174 
scandir — scan directory, 174 
scanf — convert from stdin, 261 
scanf through string — s can w, 266 
scanf through window — wscanw , 266 
scanw — scanf through string, 266 
scatter read — readv, 80 
sccsf ile — SCCS file format, 423 
schedule signal — alarm, 189 
scheduling priority 
get, 45 
set, 45 

scroll — scroll window one line, 266 
scroll window one line — scroll, 266 
scrollok — set scroll flag, 266 
sd — Adaptec ST-506 Disk driver, 331 thru 332 
sdiv — multiple precision divide, 270 
seek in directory stream — seekdir, 142 
seek on stream — f seek, 253 
seekdir — seek in directory stream, 142 
select, 89 
send, 90 

send a keyboard command ioctl — KIOCCMD, 312 

send message from socket, 90 

send signal to process, 55 

send signal to process group, 56 

sendmail aliases file — aliases, 361 

sendmsg, 90 

sendto, 90 

serial comunications driver 

serial comunications driver — z s, 355 
server at ipaddress ioctl — NDIOCSAT, 323 
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server off ioctl— NDIOCSOFF, 323 
server on ioctl — NDIOCSON, 323 
servers — inet server database, 426 
service entry 
get, 220 

inet server database — services, 427 
set arp entry ioctl — SIOCSARP, 278 
set break bit ioctl— TIOCSBRK, 345 
set cbreak mode — crmode, 266 
set clear flag for screen — clearok, 266 
set current (y,x) co-ordinates — wmove, 266 
set current domain name, 33 
set current signal mask, 99 
set date and time, 52 

set des mode ioctl — DESIOCSETKEY, 290 

set disk geometry ioctl — DKIOCSGEOM, 293 

set disk partition info ioctl — DKIOCSPART, 293 

set DTR ioctl — TIOCSDTR, 345 

set echo mode — echo, 266 

set effective group ID, 177 

set effective user ID, 177 

set ether address ioctl — NDIOCETHER, 323 

set exclusive use of tty ioctl — TIOCSETN, 344 

set exclusive use on fd ioctl — FIOCLEX, 276 

set file creation mode mask, 116 

set file owner ioctl — FIOSETOWN, 276 

set file times — utime, 200 

set high water mark ioctl — SIOCSHIWAT, 336, 348 

set ifnet address ioctl— SIOCSIFADDR, 303 

set ifnet flags ioctl— SIOCSIFFLAGS, 303 

set init vector ioctl— DESIOCSETIVEC, 290 

set keyboard translatability ioctl — KIOCTRANSABLE, 312 

set keyboard translation ioctl — KIOCTRANS, 311 

set leave flag for window — leaveok, 266 

set line discipline ioctl — TIOCSETD, 280, 338 

set local mode bits ioctl — TIOCLSET, 346 

set local special chars ioctl — TIOCSLTC, 346 

set low water mark ioctl — SIOCSLOWAT, 336, 348 

set network group entry, 217 

set network service entry, 220 

set newline mapping — nl, 266 

set options sockets, 51 

set p-p address ioctl — SIOCSIFDSTADDR, 303 

set parameters — gtty ioctl — TIOCSETP, 344 

set process group of tty ioctl — TIOCSPGRP, 345 

set program priority — nice, 192 

set raw mode — raw, 266 

set real group ID, 177 

set real user ID, 177 

set rpc program entry, 219 

set scheduling priority, 45 

set scroll flag — scrollok, 266 

set signal stack context, 100 

set special characters ioctl — TIOCSETC, 345 

set term variables for name — setterm, 266 

set terminal state — stty, 195 

set user limits — ulimit, 199 

set user mask, 1 16 


set user parameters ioctl — NDIOCUSER, 323 

set/clear async I/O ioctl — FIOASYNC, 276 

set/clear non-blocking I/O ioctl — FIONBIO, 276 

set/clear packet mode (pty) ioctl — TIOCPKT, 328 

setbuf — assign buffering, 263 

setbuffer — assign buffering, 263 

setdomainname, 33 

setegid — set effective group ID, 177 

seteuid — set effective user ID, 177 

setf sent — get file system descriptor file entry, 150 

setgid — set group ID, 177 

setgrent — get group file entry, 151 

setgroups, 91 

sethostent — get network host entry, 214 
sethostname, 38 
setitimer, 39 

set jmp — save stack environment, 175 

set jmp — non-local goto, 175 

setkey — DES encryption, 138 

setlinebuf — assign buffering, 263 

setmntent — get filesystem descriptor file entry, 153 

setnetent — get network entry, 216 

setnetgrent — get network group entry, 217 

setpgrp, 92 

setpriority, 45 

setprotoent — get protocol entry, 218 
setpwent — get password file entry, 157 
setquota, 93 
setregid, 94 
setreuid, 95 

setrgid — set real group ID, 177 
setrlimit, 46 

set rpcent — get rpc entry, 219 
set ruid — set real user ID, 177 
set servant — get service entry, 220 
setsockopt, 51 

set state — random number routines, 172 
setterm — set term variables for name, 266 
settimeof day, 52 
setuid — set user ID, 177 
shell command, issuing — system, 185 
shutdown, 96 

si — Sun SCSI Disk driver, 331 thru 332 

sigblock, 97 

signal 

schedule — alarm, 189 
stop until — pause, 193 
signal — software signals, 178 
signal messages 

signal messages — psignal, 170 
signal messages — sys_siglist, 170 
signals 

kill, 55 
killpg, 56 
sigblock, 97 
sigpause, 98 
sigsetmask, 99 
sigstack, 100 
sigvec, 101 thru 103 
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sigpause, 98 
sigsetmask, 99 
sigstack, 100 

sigvec — software signals, 101 thru 103 
simulate terminal input ioctl — TIOCSTI, 345 
sin — trigonometric sine, 209 
sinh — hyperbolic sine, 210 
SI OCADDRT — add route, 330 
SIOCATMARK — at OOB mark?, 336 
SIOCDARP — delete arp entry, 278 
SIOCDELRT — delete route, 330 
SIOCGARP — get arp entry, 278 
SIOCGHIWAT— get high watermark, 336, 348 
SI OCGIFADDR — get ifhet address, 303 
SIOCGIFCONF — get ifnet list, 303 
SIOCGIFDSTADDR — get p-p address, 303 
SIOCGIFFLAGS — get ifhet flags, 303 
SI OCGLOWAT — get low water mark, 336, 348 
SI OCSARP — set arp entry, 278 
SIOCSHIWAT — set high water mark, 336, 348 
SIOCSIFADDR — set ifhet address, 303 
SIOCSIFDSTADDR — set p-p address, 303 
SIOCSIFFLAGS — set ifnet flags, 303 
SIOCSLOWAT — set low water mark, 336, 348 
sleep — suspend execution, 181 
SMD disk controller 

±p — Interphase 2180, 309 thru3l0 
xy — Xylogics 450, 353 thru 354 
socket, 104 
socket operations 
accept, 8 
async_daemon, 68 
bind, 12 
connect, 20 
getpeername, 42 
getsockname, 50 
getsockopt, 51 
listen, 58 
nfssvc, 68 
recv, 84 
recvf rom, 84 
recvmsg, 84 
send, 90 
sendmsg, 90 
sendto, 90 
set sock opt, 51 
shutdown, 96 
socket, 104 
socketpair, 106 
socket options 
get, 51 
set, 51 

socketpair, 106 
software signal — signal, 178 
software signals 

sigvec, 101 thru 103 
sort quicker — qsort, 171 
space — specify plot space, 272 
spawn process, 121 
special file 


special file, continued 
make, 62 

special files, introduction to, 275 thru 276 
specify paging/swapping device — swapon, 111 
split into mantissa and exponent, 148 
sprintf — format to string, 257 
sqrt — square root function, 204 
square root function — sqrt, 204 
s rand — generate random numbers, 194 
s random — generate random number, 172 
s scanf — convert from string, 261 
st — Sysgen SC 4000 (Archive) Tape Driver, 333 thru 334 
standard I/O library functions 
introduction to, 247 thru 248 
standend — end standout mode, 266 
standout — start standout mode, 266 
start output (like control-Q) ioctl — TIOCSTART, 328 
start standout mode — standout, 266 
start standout mode — wstandout, 266 
stat — obtain file attributes, 107 
state of terminal 

get — gtty, 195 
set — stty, 195 

statf s — obtain file system statistics, 109 
statistics 

profil, 72 

statistics of file system — f stat f s, 109 
statistics of file system — statf s, 109 
stdin 

get character — get char, 254 
get string from — gets, 255 
input conversion — scanf, 261 
stdout 

output conversion — print f, 257 
put character to — put char, 259 
stop output (like control-S) ioctl — TIOCSTOP, 328 
stop processor, 83 
stop until signal — pause, 193 
store datum under key — store, 268 
store — store datum under key, 268 
stored current tty flags — savetty, 266 
strcat — concatenate strings, 182 
strcmp — compare strings, 182 
strcpy — copy strings, 182 
stream 

assign buffering — setbuf , 263 

assign buffering — setbuf fer, 263 

assign buffering — setlinebuf, 263 

associate descriptor — fdopen, 251 

close — fclose, 249 

flush — f flush, 249 

f print f — format to stream, 257 

get character — f get c, 254 

get character — get c, 254 

get character — get char, 254 

get position of — f tell, 253 

get string from — fgets, 255 

get word — getw, 254 

input conversion — s can f , 26 1 

open — f open, 251 
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stream, continued 

output conversion — print f, 257 
print f — format to stdout, 257 
push character back to — ungetc, 264 
put character to — fputc, 259 
put character to — putc, 259 
put string to — puts, 260 
put string to — f put s, 260 
put word to — putw, 259 
read from stream — f read, 252 
reopen — f reopen, 251 
reposition — rewind, 253 
return to remote command, 223, 224 
rewind — rewind, 253 
write to stream — f write, 252 
seek — f seek, 253 
sprintf — format to string, 257 
stream status enquiries 

clearerr — clear error on stream, 250 
f eof — enquire EOF on stream, 250 
f error — inquire error on stream, 250 
f ileno — get stream descriptor number, 250 
stream to remote command 
return, 223, 224 
stream, formatted output 

f printf — format to stream, 257 
printf — format to stdout, 257 
sprintf — format to string, 257 
streaming 1/4-inch tape drive — ar, 277 
string 

get from stdin — gets, 255 
get from stream — f get s, 255 
number conversion — printf, 257, 261 
put to stdout — puts, 260 
put to stream — fputs, 260 
string operations 

compare — strcmp, 182 
compare — strncmp, 182 
concatenate — strcat, 182 
concatenate — strncat, 182 
copy — strcpy, 182 
copy — strncpy, 182 
index — nndex, 182 
reverse index — rindex, 182 
reverse index — rindex, 182 
strings 

convert from numbers, 143 
convert to numbers, 136 
st rlen — get length of string, 182 
strncat — concatenate strings, 182 
st rncmp — compare strings, 182 
strncpy — copy strings, 182 
stty — set terminal state, 195 
subwin — create subwindow, 266 
Sun mouse device — mou se, 3 17 
Sun SCSI disk driver — s i , 33 1 thru 332 
Sun-2 10 Mb/s Ethernet interface — ie, 302 
Sun-3/50 10 Mb/s Ethernet interface — le, 313 thru 314 
super block 

update, 113 

suspend execution — sleep, 181 
swab — swap bytes, 183 


swap bytes — swab, 183 
swapon — specify paging device, 111 
swapping device — swapon, 111 
symbolic link 
create, 112 
read value of, 82 
symlink, 112 
sync, 113 

synchronize file state, 31 
synchronous I/O multiplexing, 89 
sys_errlist — system error messages, 169 
sys_nerr — system error messages, 169 
sys_siglist — system signal messages, 170 
syscall, 114 

Sysgen SC 4000 (Archive) Tape Driver — st, 333 thru 334 
syslog — write message to system log, 184 
Systech VPC-2200 interface — vpc, 350 
system calls 

introduction to, 1 thru 7 
system data types — types, 445 
system error messages 

errno — system error messages, 169 
perror — system error messages, 169 
sys_errlist — system error messages, 169 
sys_nerr — system error messages, 169 
system error numbers 

introduction to, 1 thru 5 
system — issue shell command, 185 
system log 

control, 184 

system operation support 
accounting, 10 
mount, 64 

reboot, 83 

swapon — specify paging device, 111 
sync, 113 
vadvise, 120 
system page size 
get, 41 

system resource consumption 
control — vlimit, 201 
system signal messages 

system signal messages — psignal, 170 
system signal messages — sys_siglist, 170 

T 

tan — trigonometric tangent, 209 
tanh — hyperbolic tangent, 210 
tap protocol for network — nit, 324 thru 326 
tape drive, 1/2-inch 

tm — tapemaster, 337 
xt — Xylogics 472, 352 
tape drive, 1/4-inch 

ar — Archive 1/4-inch Streaming Tape Drive, 277 
Sysgen SC 4000 (Archive) Tape Driver — st, 333 thru 334 
tape interface — mtio, 319 thru 320 
tape operation ioctl — MTIOCTOP, 319 
tapemaster 1/2-inch tape drive — tm, 337 
tar — tape archive file format, 429 
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top — Internet Transmission Control Protocol, 335 thru 336 
TCP ioctl’s 

SIOCATMARK — at OOB mark?, 336 
SIOCGHIWAT — get high water mark, 336, 348 
SIOCGLOWAT — get low water mark, 336, 348 
SIOCSHIWAT — set high water mark, 336, 348 
SIOCSLOWAT — set low water mark, 336, 348 
tell, 59 

telldir — position of directory stream, 142 
temporary file 

create name for — tmpnam, 198 
term — terminal driving tables, 431 
termcap — terminal capability data base, 434 
terminal 

configuration data base — gettytab, 380 
find name of, 186 

terminal emulation, ANSI, 285 thru 289 
ter min al emulator — cons, 285 thru 289 
terminal independent operations 
tgetent, 273 
tgetf lag, 273 
tgetnum, 273 
tgetstr, 273 
tgoto, 273 
tputs, 273 

terminal interface — tty, 338 thru 346 
terminal state 

get — gtty, 195 
set — stty, 195 
terminal types — ttytype, 444 
terminate process, 26, 147 
terminate program 

terminate program — abort, 133 
termination handler 

name — on_exit, 168 
test for indeterminate floating values 
isinf — test infinite value, 161 
isnan — test not a number, 161 
tgetent — get entry for terminal, 273 
tgetf lag — get Boolean cabability, 273 
tgetnum — get numeric cabability, 273 
tgetstr — get string cabability, 273 
tgoto — go to position, 273 
time 

adjust — adjtime, 11 
and date, get, 52 
and date, set, 52 
time and date 

get — time, 196 
get — ftime, 196 
time and date conversion 
asctime, 139 
ctime, 139 
dysize, 140 
gmtime, 139 
localtime, 139 
timezone, 139 
time — get date and time, 196 
timed event jobs table — crontab, 365 
timerclear macro, 39 
timercmp macro, 39 


timerisset macro, 39 
times — get process times, 197 
timezone — date and time conversion, 139 
timing and statistics 
getitimer, 39 
gettimeof day, 52 
profil, 72 
setitimer, 39 
settimeof day, 52 
timerclear macro, 39 
timercmp macro, 39 
timerisset macro, 39 
TIOCCBRK — clear break bit, 345 
T I OCCDTR — clear DTR, 345 
TIOCCONS — get console I/O, 285 
TIOCEXCL — clear exclusive use of tty, 344 
TIOCFLUSH — flush buffers, 345 
TIOCGETC — get special characters, 345 
TIOCGETD — get line discipline, 280, 338 
TIOCGETP — get parameters — gtty, 344 
TIOCGLTC — get local special chars, 346 
TIOCGPGRP — get process group of tty, 345 
TIOCHPCL — hang up on last close, 341, 345 
TIOCLBIC — bit clear local mode bits, 346 
TIOCLBI s — bit set local mode bits, 346 
TIOCLGET — get local mode bits, 346 
TIOCLSET — set local mode bits, 346 
TIOCNOTTY — void tty association, 338 
TIOCNXCL — remove exclusive use of tty, 344 
TIOCPKT — set/clear packet mode (pty), 328 
TIOCREMOTE — remote input editing, 328 
TIOCSBRK — set break bit, 345 
TIOCSDTR — set DTR; 345 
TIOCSETC — set special characters, 345 
TIOCSETD — set line discipline, 280, 338 
TIOCSETN — set exclusive use of tty, 344 
TIOCSETP — set parameters — gtty, 344 
TIOCSLTC — set local special chars, 346 
TIOCSPGRP — set process group of tty, 345 
TIOCSTART — start output (like control-Q), 328 
TIOCSTI — simulate terminal input, 345 
TIOCSTOP — stop output (like control-S), 328 
tm — tapemaster 1 /2-inch tape drive, 337 
tmpnam — make temporary file name, 198 
toascii — convert character to ASCII, 141 
tolower — convert character to lower-case, 141 
touchwin — change all window, 266 
toupper — convert character to upper-case, 141 
tp — DEC/mag tape formats, 442 
tputs — decode padding information, 273 
trace process — ptrace, 73 thru 75 
trigonometric functions, 209 
acos, 209 
asin, 209 
atan, 209 
atan2, 209 
cos, 209 
sin, 209 
tan, 209 
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truncate, 115 

trusted hosts list — hosts .equiv, 385 
tty — general terminal interface, 338 thru 346 
ttyname — find terminal name, 186 
ttys — terminal initialization data, 443 
ttys lot — get tty entry number, 186 
ttytype — connected terminal types, 444 
type s — primitive system data types, 445 

u 

udp — Internet User Datagram Protocol, 347 thru 348 
ulimit — get and set user limits, 199 
umask, 116 

unct rl — printable version of control, 266 
unget o — push character back to stream, 264 
unique file name 

create — mktemp, 164 

UNIX magnetic tape interface — mtio, 319 thru 320 
unlink — remove directory entry, 117 
unmap, 66 

unmap memory pages, 66 
unmount — demount file system, 1 18 
unset cbreak mode — nocrmode, 266 
unset echo mode — noecho, 266 
unset newline mapping — nonl, 266 
unset raw mode — no raw, 266 
update super block, 113 

USENET network news file formats — news, 408 
user and group ID, 177 
user ID 
get, 53 

set real and effective, 95 
user limits 

get — ulimit, 199 
set — ulimit, 199 
user mask 
set, 1 16 

ut ime — set file times, 200 

utimes, 119 

utmp — login records, 447 

uuencode — UUCP encoded file format, 448 

V 

va_arg — next argument in variable list, 187 
va_dcl — variable argument declarations, 187 

va end — finish variable argument list, 187 

va_list — variable argument declarations, 187 
va_start — initialize varargs, 187 
vadvise, 120 

varargs — variable argument list, 187 

variable argument list, 187 

version number ioctl — NDIOCVER, 323 

vf ont — font formats, 449 

vf ork, 121 

vgrindef s — vgrind language definitions, 450 
vhangup, 122 

virtual — virtual address space, 316 
vlimit — control consumption, 201 
vmel 6 — VMEbus 16-bit space, 316 


vmel 6dl 6 — VMEbus address space, 316 

vmel 6d32 — VMEbus address space, 316 

vme2 4 — VMEbus 24-bit space, 316 

vme24dl 6 — VMEbus address space, 316 

vme24d32 — VMEbus address space, 316 

vme32dl 6 — VMEbus address space, 316 

vme32d32 — VMEbus address space, 316 

void tty association ioctl — TIOCNOTTY, 338 

vp — Ikon 10071-5 Versatec parallel printer interface, 349 

vpc — Systech VPC-2200 Versatec/Centronics interface, 350 

vtimes — resource use info, 202 

w 

waddch — add character, 266 
waddstr - — add string, 266 
wait, 123 
wait3, 123 

wclear — clear window, 266 

wclrtobot — clear to bottom of window, 266 

wclrtoeol — clear to end of line, 266 

wdelch — delete character from window, 266 

wdeleteln — delete line from window, 266 

werase — erase window, 266 

wgetch — get character through window, 266 

wgetstr — get string through window, 266 

win — Sun window system, 351 

winch — get character at current (y,x) in window, 266 

winsch — insert character in, 266 

winsertln — insert line in, 266 

wmove — set current (y,x) co-ordinates, 266 

word 

get from stream — get w, 254 
put to stream — putw, 259 
working directory 
change, 14 

get pathname — getwd, 158 
wprintw — printf to window, 266 
wref resh — make screen look like window, 266 
write, 125 
write formatted 

f printf — convert to stream, 257 
printf — convert to stdout, 257 
spr intf — convert to string, 257 
write gathered — writev, 125 
write to stream — f write, 252 
wscanw — scanf through window, 266 
wstandend — end standout mode, 266 
w standout — start standout mode, 266 
wtmp — login records, 447 

X 

xt — Xylogics 472 1/2-inch tape drive, 352 
xy — Xylogics SMD Disk driver, 353 thru 354 
Xylogics 472 1/2-inch tape drive — xt, 352 
Xylogics SMD Disk driver — xy, 353 thru 354 


472 - 



Y 

yO — Bessel function, 208 
yl — Bessel function, 208 
yellow pages client interface, 229 
yn — Bessel function, 208 
yp_all — yellow pages client interface, 229 
yp bind — yellow pages client interface, 229 
yp_f irst — yellow pages client interface, 229 
yp_get_def ault_domain — yellow pages client interface, 
229 

yp_master — yellow pages client interface, 229 
yp match — yellow pages client interface, 229 
yp_next — yellow pages client interface, 229 
yporder — yellow pages client interface, 229 
yp unbind — yellow pages client interface, 229 
yperr_string — yellow pages client interface, 229 
ypf iles — yellowpages database and directory, 452 
ypprot_err — yellow pages client interface, 229 

z 

zero byte strings — bzero, 137 
z s — zilog 8530 SCC serial comunications driver, 355 
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